include/sphinxbase/sbthread.h

   1 /* -*- c-basic-offset: 4; indent-tabs-mode: nil -*- */
   2 /* ====================================================================
   3  * Copyright (c) 2008 Carnegie Mellon University.  All rights
   4  * reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  *
  10  * 1. Redistributions of source code must retain the above copyright
  11  *    notice, this list of conditions and the following disclaimer.
  12  *
  13  * 2. Redistributions in binary form must reproduce the above copyright
  14  *    notice, this list of conditions and the following disclaimer in
  15  *    the documentation and/or other materials provided with the
  16  *    distribution.
  17  *
  18  * This work was supported in part by funding from the Defense Advanced
  19  * Research Projects Agency and the National Science Foundation of the
  20  * United States of America, and the CMU Sphinx Speech Consortium.
  21  *
  22  * THIS SOFTWARE IS PROVIDED BY CARNEGIE MELLON UNIVERSITY ``AS IS'' AND
  23  * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  24  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  25  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY
  26  * NOR ITS EMPLOYEES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  27  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  28  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  29  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  30  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  32  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  *
  34  * ====================================================================
  35  *
  36  */
  37 /**
  38  * @file sbthread.h
  39  * @brief Simple portable thread functions.
  40  * @author David Huggins-Daines <dhuggins@cs.cmu.edu>
  41  **/
  42
  43 #ifndef __SBTHREAD_H__
  44 #define __SBTHREAD_H__
  45
  46 #include <sphinx_config.h>
  47
  48 #include <sphinxbase/sphinxbase_export.h>
  49 #include <sphinxbase/cmd_ln.h>
  50
  51 #ifdef __cplusplus
  52 extern "C" {
  53 #endif
  54 #if 0
  55 /* Fool Emacs. */
  56 }
  57 #endif
  58
  59 /**
  60  * Thread object.
  61  */
  62 typedef struct sbthread_s sbthread_t;
  63
  64 /**
  65  * Asynchronous message queue object.
  66  */
  67 typedef struct sbmsgq_s sbmsgq_t;
  68
  69 /**
  70  * Mutex (critical section) object.
  71  */
  72 typedef struct sbmtx_s sbmtx_t;
  73
  74 /**
  75  * Event object.
  76  */
  77 typedef struct sbevent_s sbevent_t;
  78
  79 /**
  80  * Entry point for a thread.
  81  */
  82 typedef int (*sbthread_main)(sbthread_t *th);
  83
  84 /**
  85  * Start a new thread.
  86  */
  87 SPHINXBASE_EXPORT
  88 sbthread_t *sbthread_start(cmd_ln_t *config, sbthread_main func, void *arg);
  89
  90 /**
  91  * Wait for a thread to complete.
  92  */
  93 SPHINXBASE_EXPORT
  94 int sbthread_wait(sbthread_t *th);
  95
  96 /**
  97  * Free a thread object.
  98  */
  99 SPHINXBASE_EXPORT
 100 void sbthread_free(sbthread_t *th);
 101
 102 /**
 103  * Get configuration object from a thread.
 104  */
 105 SPHINXBASE_EXPORT
 106 cmd_ln_t *sbthread_config(sbthread_t *th);
 107
 108 /**
 109  * Get argument pointer from a thread.
 110  */
 111 SPHINXBASE_EXPORT
 112 void *sbthread_arg(sbthread_t *th);
 113
 114 /**
 115  * Get message queue from a thread.
 116  */
 117 SPHINXBASE_EXPORT
 118 sbmsgq_t *sbthread_msgq(sbthread_t *th);
 119
 120 /**
 121  * Wait for a thread to complete.
 122  */
 123 SPHINXBASE_EXPORT
 124 int sbthread_wait(sbthread_t *th);
 125
 126 /**
 127  * Send an asynchronous message to a thread.
 128  *
 129  * Each thread gets a message queue by default, so this is just a
 130  * wrapper around sbmsgq_send().
 131  */
 132 SPHINXBASE_EXPORT
 133 int sbthread_send(sbthread_t *th, size_t len, void const *data);
 134
 135 /**
 136  * Create a message queue.
 137  *
 138  * @param depth Depth of the queue.
 139  */
 140 SPHINXBASE_EXPORT
 141 sbmsgq_t *sbmsgq_init(size_t depth);
 142
 143 /**
 144  * Free a message queue.
 145  */
 146 SPHINXBASE_EXPORT
 147 void sbmsgq_free(sbmsgq_t *q);
 148
 149 /**
 150  * Post a message to a queue.
 151  */
 152 SPHINXBASE_EXPORT
 153 int sbmsgq_send(sbmsgq_t *q, size_t len, void const *data);
 154
 155 /**
 156  * Wait for a message from a queue.
 157  */
 158 SPHINXBASE_EXPORT
 159 void *sbmsgq_wait(sbmsgq_t *q, size_t *out_len, int sec, int nsec);
 160
 161 /**
 162  * Create a mutex.
 163  */
 164 SPHINXBASE_EXPORT
 165 sbmtx_t *sbmtx_init(void);
 166
 167 /**
 168  * Try to acquire a mutex.
 169  */
 170 SPHINXBASE_EXPORT
 171 int sbmtx_trylock(sbmtx_t *mtx);
 172
 173 /**
 174  * Acquire a mutex.
 175  */
 176 SPHINXBASE_EXPORT
 177 int sbmtx_lock(sbmtx_t *mtx);
 178
 179 /**
 180  * Release a mutex.
 181  */
 182 SPHINXBASE_EXPORT
 183 int sbmtx_unlock(sbmtx_t *mtx);
 184
 185 /**
 186  * Dispose of a mutex.
 187  */
 188 SPHINXBASE_EXPORT
 189 void sbmtx_free(sbmtx_t *mtx);
 190
 191 /**
 192  * Initialize an event.
 193  */
 194 SPHINXBASE_EXPORT
 195 sbevent_t *sbevent_init(void);
 196
 197 /**
 198  * Free an event.
 199  */
 200 SPHINXBASE_EXPORT
 201 void sbevent_free(sbevent_t *evt);
 202
 203 /**
 204  * Signal an event.
 205  */
 206 SPHINXBASE_EXPORT
 207 int sbevent_signal(sbevent_t *evt);
 208
 209 /**
 210  * Wait for an event to be signalled.
 211  */
 212 SPHINXBASE_EXPORT
 213 int sbevent_wait(sbevent_t *evt, int sec, int nsec);
 214
 215
 216 #ifdef __cplusplus
 217 }
 218 #endif
 219
 220
 221 #endif /* __SBTHREAD_H__ */