1 /****************************************************************************** 2 * 3 * Copyright (C) 2014 Google, Inc. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at: 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 ******************************************************************************/ 18 19 #ifndef _FIXED_QUEUE_H_ 20 #define _FIXED_QUEUE_H_ 21 22 #include <stdbool.h> 23 #include "osi/list.h" 24 #include "osi/semaphore.h" 25 26 #ifndef QUEUE_SIZE_MAX 27 #define QUEUE_SIZE_MAX 254 28 #endif 29 30 #define FIXED_QUEUE_MAX_TIMEOUT OSI_SEM_MAX_TIMEOUT 31 32 struct fixed_queue_t; 33 34 typedef struct fixed_queue_t fixed_queue_t; 35 //typedef struct reactor_t reactor_t; 36 37 typedef void (*fixed_queue_free_cb)(void *data); 38 typedef void (*fixed_queue_cb)(fixed_queue_t *queue); 39 40 // Creates a new fixed queue with the given |capacity|. If more elements than 41 // |capacity| are added to the queue, the caller is blocked until space is 42 // made available in the queue. Returns NULL on failure. The caller must free 43 // the returned queue with |fixed_queue_free|. 44 fixed_queue_t *fixed_queue_new(size_t capacity); 45 46 // Freeing a queue that is currently in use (i.e. has waiters 47 // blocked on it) results in undefined behaviour. 48 void fixed_queue_free(fixed_queue_t *queue, fixed_queue_free_cb free_cb); 49 50 // Returns a value indicating whether the given |queue| is empty. If |queue| 51 // is NULL, the return value is true. 52 bool fixed_queue_is_empty(fixed_queue_t *queue); 53 54 // Returns the length of the |queue|. If |queue| is NULL, the return value 55 // is 0. 56 size_t fixed_queue_length(fixed_queue_t *queue); 57 58 // Returns the maximum number of elements this queue may hold. |queue| may 59 // not be NULL. 60 size_t fixed_queue_capacity(fixed_queue_t *queue); 61 62 // Enqueues the given |data| into the |queue|. The caller will be blocked or immediately return or wait for timeout according to the parameter timeout. 63 // If enqueue failed, it will return false, otherwise return true 64 bool fixed_queue_enqueue(fixed_queue_t *queue, void *data, uint32_t timeout); 65 66 // Dequeues the next element from |queue|. If the queue is currently empty, 67 // this function will block the caller until an item is enqueued or immediately return or wait for timeout according to the parameter timeout. 68 // If dequeue failed, it will return NULL, otherwise return a point. 69 void *fixed_queue_dequeue(fixed_queue_t *queue, uint32_t timeout); 70 71 // Returns the first element from |queue|, if present, without dequeuing it. 72 // This function will never block the caller. Returns NULL if there are no 73 // elements in the queue or |queue| is NULL. 74 void *fixed_queue_try_peek_first(fixed_queue_t *queue); 75 76 // Returns the last element from |queue|, if present, without dequeuing it. 77 // This function will never block the caller. Returns NULL if there are no 78 // elements in the queue or |queue| is NULL. 79 void *fixed_queue_try_peek_last(fixed_queue_t *queue); 80 81 // Tries to remove a |data| element from the middle of the |queue|. This 82 // function will never block the caller. If the queue is empty or NULL, this 83 // function returns NULL immediately. |data| may not be NULL. If the |data| 84 // element is found in the queue, a pointer to the removed data is returned, 85 // otherwise NULL. 86 void *fixed_queue_try_remove_from_queue(fixed_queue_t *queue, void *data); 87 88 // Returns the iterateable list with all entries in the |queue|. This function 89 // will never block the caller. |queue| may not be NULL. 90 // 91 // NOTE: The return result of this function is not thread safe: the list could 92 // be modified by another thread, and the result would be unpredictable. 93 // TODO: The usage of this function should be refactored, and the function 94 // itself should be removed. 95 list_t *fixed_queue_get_list(fixed_queue_t *queue); 96 97 // This function returns a valid file descriptor. Callers may perform one 98 // operation on the fd: select(2). If |select| indicates that the file 99 // descriptor is readable, the caller may call |fixed_queue_enqueue| without 100 // blocking. The caller must not close the returned file descriptor. |queue| 101 // may not be NULL. 102 //int fixed_queue_get_enqueue_fd(const fixed_queue_t *queue); 103 104 // This function returns a valid file descriptor. Callers may perform one 105 // operation on the fd: select(2). If |select| indicates that the file 106 // descriptor is readable, the caller may call |fixed_queue_dequeue| without 107 // blocking. The caller must not close the returned file descriptor. |queue| 108 // may not be NULL. 109 //int fixed_queue_get_dequeue_fd(const fixed_queue_t *queue); 110 111 // Registers |queue| with |reactor| for dequeue operations. When there is an element 112 // in the queue, ready_cb will be called. The |context| parameter is passed, untouched, 113 // to the callback routine. Neither |queue|, nor |reactor|, nor |read_cb| may be NULL. 114 // |context| may be NULL. 115 void fixed_queue_register_dequeue(fixed_queue_t *queue, fixed_queue_cb ready_cb); 116 117 // Unregisters the dequeue ready callback for |queue| from whichever reactor 118 // it is registered with, if any. This function is idempotent. 119 void fixed_queue_unregister_dequeue(fixed_queue_t *queue); 120 121 void fixed_queue_process(fixed_queue_t *queue); 122 123 list_t *fixed_queue_get_list(fixed_queue_t *queue); 124 125 #endif 126
