1 /****************************************************************************** 2 * 3 * Copyright 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 #pragma once 20 21 #include <stdbool.h> 22 #include <stdlib.h> 23 24 #include "osi/include/list.h" 25 26 struct fixed_queue_t; 27 typedef struct fixed_queue_t fixed_queue_t; 28 typedef struct reactor_t reactor_t; 29 30 typedef void (*fixed_queue_free_cb)(void* data); 31 typedef void (*fixed_queue_cb)(fixed_queue_t* queue, void* context); 32 33 // Creates a new fixed queue with the given |capacity|. If more elements than 34 // |capacity| are added to the queue, the caller is blocked until space is 35 // made available in the queue. Returns NULL on failure. The caller must free 36 // the returned queue with |fixed_queue_free|. 37 fixed_queue_t* fixed_queue_new(size_t capacity); 38 39 // Frees a queue and (optionally) the enqueued elements. 40 // |queue| is the queue to free. If the |free_cb| callback is not null, 41 // it is called on each queue element to free it. 42 // Freeing a queue that is currently in use (i.e. has waiters 43 // blocked on it) results in undefined behaviour. 44 void fixed_queue_free(fixed_queue_t* queue, fixed_queue_free_cb free_cb); 45 46 // Flushes a queue and (optionally) frees the enqueued elements. 47 // |queue| is the queue to flush. If the |free_cb| callback is not null, 48 // it is called on each queue element to free it. 49 void fixed_queue_flush(fixed_queue_t* queue, fixed_queue_free_cb free_cb); 50 51 // Returns a value indicating whether the given |queue| is empty. If |queue| 52 // is NULL, the return value is true. 53 bool fixed_queue_is_empty(fixed_queue_t* queue); 54 55 // Returns the length of the |queue|. If |queue| is NULL, the return value 56 // is 0. 57 size_t fixed_queue_length(fixed_queue_t* queue); 58 59 // Returns the maximum number of elements this queue may hold. |queue| may 60 // not be NULL. 61 size_t fixed_queue_capacity(fixed_queue_t* queue); 62 63 // Enqueues the given |data| into the |queue|. The caller will be blocked 64 // if no more space is available in the queue. Neither |queue| nor |data| 65 // may be NULL. 66 void fixed_queue_enqueue(fixed_queue_t* queue, void* data); 67 68 // Dequeues the next element from |queue|. If the queue is currently empty, 69 // this function will block the caller until an item is enqueued. This 70 // function will never return NULL. |queue| may not be NULL. 71 void* fixed_queue_dequeue(fixed_queue_t* queue); 72 73 // Tries to enqueue |data| into the |queue|. This function will never block 74 // the caller. If the queue capacity would be exceeded by adding one more 75 // element, this function returns false immediately. Otherwise, this function 76 // returns true. Neither |queue| nor |data| may be NULL. 77 bool fixed_queue_try_enqueue(fixed_queue_t* queue, void* data); 78 79 // Tries to dequeue an element from |queue|. This function will never block 80 // the caller. If the queue is empty or NULL, this function returns NULL 81 // immediately. Otherwise, the next element in the queue is returned. 82 void* fixed_queue_try_dequeue(fixed_queue_t* queue); 83 84 // Returns the first element from |queue|, if present, without dequeuing it. 85 // This function will never block the caller. Returns NULL if there are no 86 // elements in the queue or |queue| is NULL. 87 void* fixed_queue_try_peek_first(fixed_queue_t* queue); 88 89 // Returns the last element from |queue|, if present, without dequeuing it. 90 // This function will never block the caller. Returns NULL if there are no 91 // elements in the queue or |queue| is NULL. 92 void* fixed_queue_try_peek_last(fixed_queue_t* queue); 93 94 // Tries to remove a |data| element from the middle of the |queue|. This 95 // function will never block the caller. If the queue is empty or NULL, this 96 // function returns NULL immediately. |data| may not be NULL. If the |data| 97 // element is found in the queue, a pointer to the removed data is returned, 98 // otherwise NULL. 99 void* fixed_queue_try_remove_from_queue(fixed_queue_t* queue, void* data); 100 101 // Returns the iterateable list with all entries in the |queue|. This function 102 // will never block the caller. |queue| may not be NULL. 103 // 104 // NOTE: The return result of this function is not thread safe: the list could 105 // be modified by another thread, and the result would be unpredictable. 106 // TODO: The usage of this function should be refactored, and the function 107 // itself should be removed. 108 list_t* fixed_queue_get_list(fixed_queue_t* queue); 109 110 // This function returns a valid file descriptor. Callers may perform one 111 // operation on the fd: select(2). If |select| indicates that the file 112 // descriptor is readable, the caller may call |fixed_queue_enqueue| without 113 // blocking. The caller must not close the returned file descriptor. |queue| 114 // may not be NULL. 115 int fixed_queue_get_enqueue_fd(const fixed_queue_t* queue); 116 117 // This function returns a valid file descriptor. Callers may perform one 118 // operation on the fd: select(2). If |select| indicates that the file 119 // descriptor is readable, the caller may call |fixed_queue_dequeue| without 120 // blocking. The caller must not close the returned file descriptor. |queue| 121 // may not be NULL. 122 int fixed_queue_get_dequeue_fd(const fixed_queue_t* queue); 123 124 // Registers |queue| with |reactor| for dequeue operations. When there is an 125 // element in the queue, ready_cb will be called. The |context| parameter is 126 // passed, untouched, to the callback routine. Neither |queue|, nor |reactor|, 127 // nor |read_cb| may be NULL. |context| may be NULL. 128 void fixed_queue_register_dequeue(fixed_queue_t* queue, reactor_t* reactor, 129 fixed_queue_cb ready_cb, void* context); 130 131 // Unregisters the dequeue ready callback for |queue| from whichever reactor 132 // it is registered with, if any. This function is idempotent. 133 void fixed_queue_unregister_dequeue(fixed_queue_t* queue); 134