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 #pragma once 20 21 #include <stdbool.h> 22 23 struct fixed_queue_t; 24 typedef struct fixed_queue_t fixed_queue_t; 25 typedef struct reactor_t reactor_t; 26 27 typedef void (*fixed_queue_free_cb)(void *data); 28 typedef void (*fixed_queue_cb)(fixed_queue_t *queue, void *context); 29 30 // Creates a new fixed queue with the given |capacity|. If more elements than 31 // |capacity| are added to the queue, the caller is blocked until space is 32 // made available in the queue. Returns NULL on failure. The caller must free 33 // the returned queue with |fixed_queue_free|. 34 fixed_queue_t *fixed_queue_new(size_t capacity); 35 36 // Freeing a queue that is currently in use (i.e. has waiters 37 // blocked on it) results in undefined behaviour. 38 void fixed_queue_free(fixed_queue_t *queue, fixed_queue_free_cb free_cb); 39 40 // Returns a value indicating whether the given |queue| is empty. |queue| may 41 // not be NULL. 42 bool fixed_queue_is_empty(fixed_queue_t *queue); 43 44 // Returns the maximum number of elements this queue may hold. |queue| may 45 // not be NULL. 46 size_t fixed_queue_capacity(fixed_queue_t *queue); 47 48 // Enqueues the given |data| into the |queue|. The caller will be blocked 49 // if nore more space is available in the queue. Neither |queue| nor |data| 50 // may be NULL. 51 void fixed_queue_enqueue(fixed_queue_t *queue, void *data); 52 53 // Dequeues the next element from |queue|. If the queue is currently empty, 54 // this function will block the caller until an item is enqueued. This 55 // function will never return NULL. |queue| may not be NULL. 56 void *fixed_queue_dequeue(fixed_queue_t *queue); 57 58 // Tries to enqueue |data| into the |queue|. This function will never block 59 // the caller. If the queue capacity would be exceeded by adding one more 60 // element, this function returns false immediately. Otherwise, this function 61 // returns true. Neither |queue| nor |data| may be NULL. 62 bool fixed_queue_try_enqueue(fixed_queue_t *queue, void *data); 63 64 // Tries to dequeue an element from |queue|. This function will never block 65 // the caller. If the queue is empty, this function returns NULL immediately. 66 // Otherwise, the next element in the queue is returned. |queue| may not be 67 // NULL. 68 void *fixed_queue_try_dequeue(fixed_queue_t *queue); 69 70 // Returns the first element from |queue|, if present, without dequeuing it. 71 // This function will never block the caller. Returns NULL if there are no elements 72 // in the queue. |queue| may not be NULL. 73 void *fixed_queue_try_peek(fixed_queue_t *queue); 74 75 // This function returns a valid file descriptor. Callers may perform one 76 // operation on the fd: select(2). If |select| indicates that the file 77 // descriptor is readable, the caller may call |fixed_queue_enqueue| without 78 // blocking. The caller must not close the returned file descriptor. |queue| 79 // may not be NULL. 80 int fixed_queue_get_enqueue_fd(const fixed_queue_t *queue); 81 82 // This function returns a valid file descriptor. Callers may perform one 83 // operation on the fd: select(2). If |select| indicates that the file 84 // descriptor is readable, the caller may call |fixed_queue_dequeue| without 85 // blocking. The caller must not close the returned file descriptor. |queue| 86 // may not be NULL. 87 int fixed_queue_get_dequeue_fd(const fixed_queue_t *queue); 88 89 // Registers |queue| with |reactor| for dequeue operations. When there is an element 90 // in the queue, ready_cb will be called. The |context| parameter is passed, untouched, 91 // to the callback routine. Neither |queue|, nor |reactor|, nor |read_cb| may be NULL. 92 // |context| may be NULL. 93 void fixed_queue_register_dequeue(fixed_queue_t *queue, reactor_t *reactor, fixed_queue_cb ready_cb, void *context); 94 95 // Unregisters the dequeue ready callback for |queue| from whichever reactor 96 // it is registered with, if any. This function is idempotent. 97 void fixed_queue_unregister_dequeue(fixed_queue_t *queue); 98