osi/include/fixed_queue.h

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