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
23struct fixed_queue_t;
24typedef struct fixed_queue_t fixed_queue_t;
25
26typedef void (*fixed_queue_free_cb)(void *data);
27
28// Creates a new fixed queue with the given |capacity|. If more elements than
29// |capacity| are added to the queue, the caller is blocked until space is
30// made available in the queue. Returns NULL on failure. The caller must free
31// the returned queue with |fixed_queue_free|.
32fixed_queue_t *fixed_queue_new(size_t capacity);
33
34// Freeing a queue that is currently in use (i.e. has waiters
35// blocked on it) results in undefined behaviour.
36void fixed_queue_free(fixed_queue_t *queue, fixed_queue_free_cb free_cb);
37
38// Enqueues the given |data| into the |queue|. The caller will be blocked
39// if nore more space is available in the queue. Neither |queue| nor |data|
40// may be NULL.
41void fixed_queue_enqueue(fixed_queue_t *queue, void *data);
42
43// Dequeues the next element from |queue|. If the queue is currently empty,
44// this function will block the caller until an item is enqueued. This
45// function will never return NULL. |queue| may not be NULL.
46void *fixed_queue_dequeue(fixed_queue_t *queue);
47
48// Tries to enqueue |data| into the |queue|. This function will never block
49// the caller. If the queue capacity would be exceeded by adding one more
50// element, this function returns false immediately. Otherwise, this function
51// returns true. Neither |queue| nor |data| may be NULL.
52bool fixed_queue_try_enqueue(fixed_queue_t *queue, void *data);
53
54// Tries to dequeue an element from |queue|. This function will never block
55// the caller. If the queue is empty, this function returns NULL immediately.
56// Otherwise, the next element in the queue is returned. |queue| may not be
57// NULL.
58void *fixed_queue_try_dequeue(fixed_queue_t *queue);
59
60// This function returns a valid file descriptor. Callers may perform one
61// operation on the fd: select(2). If |select| indicates that the file
62// descriptor is readable, the caller may call |fixed_queue_enqueue| without
63// blocking. The caller must not close the returned file descriptor. |queue|
64// may not be NULL.
65int fixed_queue_get_enqueue_fd(const fixed_queue_t *queue);
66
67// This function returns a valid file descriptor. Callers may perform one
68// operation on the fd: select(2). If |select| indicates that the file
69// descriptor is readable, the caller may call |fixed_queue_dequeue| without
70// blocking. The caller must not close the returned file descriptor. |queue|
71// may not be NULL.
72int fixed_queue_get_dequeue_fd(const fixed_queue_t *queue);
73