lib/silcutil/silcthreadqueue.h

   1 /*
   2
   3   silcthreadqueue.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2008 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/Thread Queue Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * This interface provides asynchronous thread queues that can be used to
  25  * pass messages and data between two or more threads.  Typically a thread
  26  * would create the queue, push data into the queue and some other thread
  27  * takes the data from the queue or blocks until more data is available
  28  * in the queue.
  29  *
  30  * EXAMPLE
  31  *
  32  * Thread 1:
  33  *
  34  * // Create queue and push data into it
  35  * SilcThreadQueue queue = silc_thread_queue_alloc();
  36  * silc_thread_queue_push(queue, data);
  37  *
  38  * Thread 2:
  39  *
  40  * // Connect to the queue
  41  * silc_thread_queue_connect(queue);
  42  *
  43  * // Block here until data is available from the queue
  44  * data = silc_thread_queue_pop(queue, TRUE);
  45  *
  46  ***/
  47
  48 #ifndef SILCTHREADQUEUE_H
  49 #define SILCTHREADQUEUE_H
  50
  51 /****s* silcutil/SilcThreadQueue
  52  *
  53  * NAME
  54  *
  55  *    typedef struct SilcThreadQueueStruct *SilcThreadQueue;
  56  *
  57  * DESCRIPTION
  58  *
  59  *    The thread queue context allocated by silc_thread_queue_alloc and
  60  *    given as argument to all silc_thread_queue_* functions.
  61  *
  62  ***/
  63 typedef struct SilcThreadQueueStruct *SilcThreadQueue;
  64
  65 /****f* silcutil/silc_thread_queue_alloc
  66  *
  67  * SYNOPSIS
  68  *
  69  *    SilcThreadQueue silc_thread_queue_alloc(void);
  70  *
  71  * DESCRIPTION
  72  *
  73  *    Allocates new thread queue context and returns it.  Returns NULL in
  74  *    case of error and sets the silc_errno.  The returned context is
  75  *    immediately ready to be used.  For a thread to be able to use the
  76  *    queue it must first connect to it by calling silc_thread_queue_connect.
  77  *    The thread that creates the queue automatically connects to the queue.
  78  *
  79  ***/
  80 SilcThreadQueue silc_thread_queue_alloc(void);
  81
  82 /****f* silcutil/silc_thread_queue_connect
  83  *
  84  * SYNOPSIS
  85  *
  86  *    SilcBool silc_thread_queue_connect(SilcThreadQueue queue);
  87  *
  88  * DESCRIPTION
  89  *
  90  *    Connects current thread to the thread queue.  This function must
  91  *    be called by each thread wanting to use the thread queue.  After the
  92  *    thread is finished using the queue it must disconnect from the queue
  93  *    by calling silc_thread_queue_disconnect.
  94  *
  95  ***/
  96 void silc_thread_queue_connect(SilcThreadQueue queue);
  97
  98 /****f* silcutil/silc_thread_queue_disconnect
  99  *
 100  * SYNOPSIS
 101  *
 102  *    void silc_thread_queue_disconnect(SilcThreadQueue queue);
 103  *
 104  * DESCRIPTION
 105  *
 106  *    Disconnects the current thread from the thread queue.  This must be
 107  *    called after the thread has finished using the thread queue.
 108  *
 109  *    When the last thread has disconnected from the queue the queue is
 110  *    destroyed.
 111  *
 112  ***/
 113 void silc_thread_queue_disconnect(SilcThreadQueue queue);
 114
 115 /****f* silcutil/silc_thread_queue_push
 116  *
 117  * SYNOPSIS
 118  *
 119  *    void silc_thread_queue_push(SilcThreadQueue queue, void *data);
 120  *
 121  * DESCRIPTION
 122  *
 123  *    Pushes the `data' into the thread queue.  The data will become
 124  *    immediately available in the queue for other threads.
 125  *
 126  ***/
 127 void silc_thread_queue_push(SilcThreadQueue queue, void *data);
 128
 129 /****f* silcutil/silc_thread_queue_pop
 130  *
 131  * SYNOPSIS
 132  *
 133  *    void *silc_thread_queue_pop(SilcThreadQueue queue, SilcBool block);
 134  *
 135  * DESCRIPTION
 136  *
 137  *    Takes data from the queue and returns it.  If `block' is TRUE and
 138  *    data is not available this will block until data becomes available.
 139  *    If `block' is FALSE and data is not available this will return NULL.
 140  *    If `block' is TRUE this will never return NULL.
 141  *
 142  ***/
 143 void *silc_thread_queue_pop(SilcThreadQueue queue, SilcBool block);
 144
 145 /****f* silcutil/silc_thread_queue_timed_pop
 146  *
 147  * SYNOPSIS
 148  *
 149  *    void *silc_thread_queue_timed_pop(SilcThreadQueue queue,
 150  *                                      int timeout_msec);
 151  *
 152  * DESCRIPTION
 153  *
 154  *    Takes data from the thread queue or waits at most `timeout_msec'
 155  *    milliseconds for the data to arrive.  If data is not available when
 156  *    the timeout occurrs this returns NULL.
 157  *
 158  ***/
 159 void *silc_thread_queue_timed_pop(SilcThreadQueue queue,
 160                                   int timeout_msec);
 161
 162 /****f* silcutil/silc_thread_queue_pop_list
 163  *
 164  * SYNOPSIS
 165  *
 166  *    SilcDList silc_thread_queue_pop_list(SilcThreadQueue queue,
 167  *                                         SilcBool block);
 168  *
 169  * DESCRIPTION
 170  *
 171  *    Takes everything from the queue and returns the data in a list.  The
 172  *    caller must free the returned list with silc_dlist_uninit.  If the
 173  *    `block' is FALSE this will never block but will return the queue
 174  *    immediately.  If `block' is TRUE this will block if the queue is
 175  *    empty.
 176  *
 177  ***/
 178 SilcDList silc_thread_queue_pop_list(SilcThreadQueue queue, SilcBool block);
 179
 180 #endif /* SILCTHREADQUEUE_H */