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