src/libstrongswan/collections/blocking_queue.h

   1 /*
   2  * Copyright (C) 2012 Tobias Brunner
   3  * Copyright (C) 2012 Giuliano Grassi
   4  * Copyright (C) 2012 Ralf Sager
   5  * Hochschule fuer Technik Rapperswil
   6  *
   7  * This program is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU General Public License as published by the
   9  * Free Software Foundation; either version 2 of the License, or (at your
  10  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  11  *
  12  * This program is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  14  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15  * for more details.
  16  */
  17
  18 /**
  19  * @defgroup blocking_queue blocking_queue
  20  * @{ @ingroup collections
  21  */
  22
  23 #ifndef BLOCKING_QUEUE_H_
  24 #define BLOCKING_QUEUE_H_
  25
  26 typedef struct blocking_queue_t blocking_queue_t;
  27
  28 #include <library.h>
  29
  30 /**
  31  * Class implementing a synchronized blocking queue based on linked_list_t
  32  */
  33 struct blocking_queue_t {
  34
  35         /**
  36          * Inserts a new item at the tail of the queue
  37          *
  38          * @param item          item to insert in queue
  39          */
  40         void (*enqueue)(blocking_queue_t *this, void *item);
  41
  42         /**
  43          * Removes the first item in the queue and returns its value.
  44          * If the queue is empty, this call blocks until a new item is inserted.
  45          *
  46          * @note This is a thread cancellation point
  47          *
  48          * @return                      removed item
  49          */
  50         void *(*dequeue)(blocking_queue_t *this);
  51
  52         /**
  53          * Destroys a blocking_queue_t object.
  54          *
  55          * @note No thread must wait in dequeue() when this function is called
  56          */
  57         void (*destroy)(blocking_queue_t *this);
  58
  59         /**
  60          * Destroys a queue and its objects using the given destructor.
  61          *
  62          * If a queue and the contained objects should be destroyed, use
  63          * destroy_offset. The supplied offset specifies the destructor to
  64          * call on each object. The offset may be calculated using the offsetof
  65          * macro, e.g.: queue->destroy_offset(queue, offsetof(object_t, destroy));
  66          *
  67          * @note No thread must wait in dequeue() when this function is called
  68          *
  69          * @param offset        offset of the objects destructor
  70          */
  71         void (*destroy_offset)(blocking_queue_t *this, size_t offset);
  72
  73         /**
  74          * Destroys a queue and its objects using a cleanup function.
  75          *
  76          * If a queue and its contents should get destroyed using a specific
  77          * cleanup function, use destroy_function. This is useful when the
  78          * list contains malloc()-ed blocks which should get freed,
  79          * e.g.: queue->destroy_function(queue, free);
  80          *
  81          * @note No thread must wait in dequeue() when this function is called
  82          *
  83          * @param function      function to call on each object
  84          */
  85         void (*destroy_function)(blocking_queue_t *this, void (*)(void*));
  86
  87 };
  88
  89 /**
  90  * Creates an empty queue object.
  91  *
  92  * @return              blocking_queue_t object.
  93  */
  94 blocking_queue_t *blocking_queue_create();
  95
  96 #endif /** BLOCKING_QUEUE_H_ @}*/
  97