Sharvil Nanavati | c5856ba | 2014-06-23 12:25:40 -0700 | [diff] [blame] | 1 | /****************************************************************************** |
| 2 | * |
Jakub Pawlowski | 5b790fe | 2017-09-18 09:00:20 -0700 | [diff] [blame] | 3 | * Copyright 2014 Google, Inc. |
Sharvil Nanavati | c5856ba | 2014-06-23 12:25:40 -0700 | [diff] [blame] | 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 | |
Sharvil Nanavati | c11b407 | 2014-05-02 23:55:09 -0700 | [diff] [blame] | 19 | #pragma once |
| 20 | |
Sharvil Nanavati | c5856ba | 2014-06-23 12:25:40 -0700 | [diff] [blame] | 21 | #include <stdbool.h> |
Marie Janssen | 49a8670 | 2015-07-08 11:48:57 -0700 | [diff] [blame] | 22 | #include <stdlib.h> |
Sharvil Nanavati | c11b407 | 2014-05-02 23:55:09 -0700 | [diff] [blame] | 23 | |
Pavlin Radoslavov | 1a3844f | 2015-09-25 11:21:15 -0700 | [diff] [blame] | 24 | #include "osi/include/list.h" |
| 25 | |
Sharvil Nanavati | c11b407 | 2014-05-02 23:55:09 -0700 | [diff] [blame] | 26 | struct fixed_queue_t; |
| 27 | typedef struct fixed_queue_t fixed_queue_t; |
Zach Johnson | bd522a4 | 2014-08-15 16:44:46 -0700 | [diff] [blame] | 28 | typedef struct reactor_t reactor_t; |
Sharvil Nanavati | c11b407 | 2014-05-02 23:55:09 -0700 | [diff] [blame] | 29 | |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 30 | typedef void (*fixed_queue_free_cb)(void* data); |
| 31 | typedef void (*fixed_queue_cb)(fixed_queue_t* queue, void* context); |
Sharvil Nanavati | c11b407 | 2014-05-02 23:55:09 -0700 | [diff] [blame] | 32 | |
Sharvil Nanavati | c5856ba | 2014-06-23 12:25:40 -0700 | [diff] [blame] | 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|. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 37 | fixed_queue_t* fixed_queue_new(size_t capacity); |
Sharvil Nanavati | c11b407 | 2014-05-02 23:55:09 -0700 | [diff] [blame] | 38 | |
Pavlin Radoslavov | 3335cf4 | 2016-08-19 15:32:30 -0700 | [diff] [blame] | 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. |
Sharvil Nanavati | c11b407 | 2014-05-02 23:55:09 -0700 | [diff] [blame] | 42 | // Freeing a queue that is currently in use (i.e. has waiters |
Sharvil Nanavati | c5856ba | 2014-06-23 12:25:40 -0700 | [diff] [blame] | 43 | // blocked on it) results in undefined behaviour. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 44 | void fixed_queue_free(fixed_queue_t* queue, fixed_queue_free_cb free_cb); |
Sharvil Nanavati | c11b407 | 2014-05-02 23:55:09 -0700 | [diff] [blame] | 45 | |
Pavlin Radoslavov | 3335cf4 | 2016-08-19 15:32:30 -0700 | [diff] [blame] | 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. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 49 | void fixed_queue_flush(fixed_queue_t* queue, fixed_queue_free_cb free_cb); |
Pavlin Radoslavov | 3335cf4 | 2016-08-19 15:32:30 -0700 | [diff] [blame] | 50 | |
Pavlin Radoslavov | 577862e | 2015-10-07 18:07:48 -0700 | [diff] [blame] | 51 | // Returns a value indicating whether the given |queue| is empty. If |queue| |
| 52 | // is NULL, the return value is true. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 53 | bool fixed_queue_is_empty(fixed_queue_t* queue); |
Zach Johnson | 93a1c80 | 2014-07-30 13:40:09 -0700 | [diff] [blame] | 54 | |
Pavlin Radoslavov | 577862e | 2015-10-07 18:07:48 -0700 | [diff] [blame] | 55 | // Returns the length of the |queue|. If |queue| is NULL, the return value |
| 56 | // is 0. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 57 | size_t fixed_queue_length(fixed_queue_t* queue); |
Pavlin Radoslavov | 1a3844f | 2015-09-25 11:21:15 -0700 | [diff] [blame] | 58 | |
Chris Manton | c446cbe | 2014-08-05 11:07:23 -0700 | [diff] [blame] | 59 | // Returns the maximum number of elements this queue may hold. |queue| may |
| 60 | // not be NULL. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 61 | size_t fixed_queue_capacity(fixed_queue_t* queue); |
Chris Manton | c446cbe | 2014-08-05 11:07:23 -0700 | [diff] [blame] | 62 | |
Sharvil Nanavati | c5856ba | 2014-06-23 12:25:40 -0700 | [diff] [blame] | 63 | // Enqueues the given |data| into the |queue|. The caller will be blocked |
Pavlin Radoslavov | 153bdfb | 2015-11-13 18:36:56 -0800 | [diff] [blame] | 64 | // if no more space is available in the queue. Neither |queue| nor |data| |
Sharvil Nanavati | c5856ba | 2014-06-23 12:25:40 -0700 | [diff] [blame] | 65 | // may be NULL. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 66 | void fixed_queue_enqueue(fixed_queue_t* queue, void* data); |
Sharvil Nanavati | c5856ba | 2014-06-23 12:25:40 -0700 | [diff] [blame] | 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. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 71 | void* fixed_queue_dequeue(fixed_queue_t* queue); |
Sharvil Nanavati | c5856ba | 2014-06-23 12:25:40 -0700 | [diff] [blame] | 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. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 77 | bool fixed_queue_try_enqueue(fixed_queue_t* queue, void* data); |
Sharvil Nanavati | c5856ba | 2014-06-23 12:25:40 -0700 | [diff] [blame] | 78 | |
| 79 | // Tries to dequeue an element from |queue|. This function will never block |
Pavlin Radoslavov | 577862e | 2015-10-07 18:07:48 -0700 | [diff] [blame] | 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. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 82 | void* fixed_queue_try_dequeue(fixed_queue_t* queue); |
Sharvil Nanavati | ab606b5 | 2014-07-04 16:33:37 -0700 | [diff] [blame] | 83 | |
Zach Johnson | bd522a4 | 2014-08-15 16:44:46 -0700 | [diff] [blame] | 84 | // Returns the first element from |queue|, if present, without dequeuing it. |
Pavlin Radoslavov | 1a3844f | 2015-09-25 11:21:15 -0700 | [diff] [blame] | 85 | // This function will never block the caller. Returns NULL if there are no |
Pavlin Radoslavov | 577862e | 2015-10-07 18:07:48 -0700 | [diff] [blame] | 86 | // elements in the queue or |queue| is NULL. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 87 | void* fixed_queue_try_peek_first(fixed_queue_t* queue); |
Pavlin Radoslavov | 1a3844f | 2015-09-25 11:21:15 -0700 | [diff] [blame] | 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 |
Pavlin Radoslavov | 577862e | 2015-10-07 18:07:48 -0700 | [diff] [blame] | 91 | // elements in the queue or |queue| is NULL. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 92 | void* fixed_queue_try_peek_last(fixed_queue_t* queue); |
Pavlin Radoslavov | 1a3844f | 2015-09-25 11:21:15 -0700 | [diff] [blame] | 93 | |
| 94 | // Tries to remove a |data| element from the middle of the |queue|. This |
Pavlin Radoslavov | 153bdfb | 2015-11-13 18:36:56 -0800 | [diff] [blame] | 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. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 99 | void* fixed_queue_try_remove_from_queue(fixed_queue_t* queue, void* data); |
Pavlin Radoslavov | 1a3844f | 2015-09-25 11:21:15 -0700 | [diff] [blame] | 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. |
Pavlin Radoslavov | 153bdfb | 2015-11-13 18:36:56 -0800 | [diff] [blame] | 106 | // TODO: The usage of this function should be refactored, and the function |
| 107 | // itself should be removed. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 108 | list_t* fixed_queue_get_list(fixed_queue_t* queue); |
Zach Johnson | bd522a4 | 2014-08-15 16:44:46 -0700 | [diff] [blame] | 109 | |
Sharvil Nanavati | ab606b5 | 2014-07-04 16:33:37 -0700 | [diff] [blame] | 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. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 115 | int fixed_queue_get_enqueue_fd(const fixed_queue_t* queue); |
Sharvil Nanavati | ab606b5 | 2014-07-04 16:33:37 -0700 | [diff] [blame] | 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. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 122 | int fixed_queue_get_dequeue_fd(const fixed_queue_t* queue); |
Zach Johnson | bd522a4 | 2014-08-15 16:44:46 -0700 | [diff] [blame] | 123 | |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 124 | // Registers |queue| with |reactor| for dequeue operations. When there is an |
Myles Watson | 9ca0709 | 2016-11-28 16:41:53 -0800 | [diff] [blame] | 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. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 128 | void fixed_queue_register_dequeue(fixed_queue_t* queue, reactor_t* reactor, |
| 129 | fixed_queue_cb ready_cb, void* context); |
Zach Johnson | bd522a4 | 2014-08-15 16:44:46 -0700 | [diff] [blame] | 130 | |
| 131 | // Unregisters the dequeue ready callback for |queue| from whichever reactor |
| 132 | // it is registered with, if any. This function is idempotent. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame] | 133 | void fixed_queue_unregister_dequeue(fixed_queue_t* queue); |