include/ddekit/thread.h

   1 #ifndef _DDEKIT_THREAD_H
   2 #define _DDEKIT_THREAD_H
   3
   4 /** \defgroup DDEKit_threads */
   5 #include <ddekit/ddekit.h>
   6 #include <ddekit/lock.h>
   7
   8 struct ddekit_thread;
   9 typedef struct ddekit_thread ddekit_thread_t;
  10
  11 /** Create thread
  12  *
  13  * \ingroup DDEKit_threads
  14  *
  15  * Create a new thread running the specified thread function with the specified
  16  * arguments. The thread is assigned the given internal name.
  17  *
  18  * Additionally, DDEKit threads possess a thread-local storage area where they
  19  * may store arbitrary data.
  20  *
  21  * \param fun     thread function
  22  * \param arg     optional argument to thread function, set to NULL if not needed
  23  * \param name    internal thread name
  24  */
  25 ddekit_thread_t *ddekit_thread_create(void (*fun)(void *), void *arg,
  26         const char *name);
  27
  28 /** Reference to own DDEKit thread id.
  29  *
  30  * \ingroup DDEKit_threads
  31  */
  32 ddekit_thread_t *ddekit_thread_myself(void);
  33
  34 /** Initialize thread with given name.
  35  *
  36  * \ingroup DDEKit_threads
  37  *
  38  * This function may be used by threads that were not created using
  39  * \ref ddekit_thread_create. This enables such threads to be handled as if they
  40  * were DDEKit threads.
  41  */
  42 ddekit_thread_t *ddekit_thread_setup_myself(const char *name);
  43
  44 /** Get TLS data for a specific thread.
  45  *
  46  * \ingroup DDEKit_threads
  47  *
  48  * \return Pointer to TLS data of this thread.
  49  */
  50 void *ddekit_thread_get_data(ddekit_thread_t *thread);
  51
  52 /** Get TLS data for current thread.
  53  *
  54  * \ingroup DDEKit_threads
  55  *
  56  * Same as calling \ref ddekit_thread_get_data with \ref ddekit_thread_myself
  57  * as parameter.
  58  *
  59  * \return Pointer to TLS data of current thread.
  60  */
  61 void *ddekit_thread_get_my_data(void);
  62
  63 /** Set TLS data for specific thread.
  64  *
  65  * \ingroup DDEKit_threads
  66  *
  67  * \param thread     DDEKit thread
  68  * \param data       pointer to thread data
  69  */
  70 void ddekit_thread_set_data(ddekit_thread_t *thread, void *data);
  71
  72 /** Set TLS data for current thread.
  73  *
  74  * \ingroup DDEKit_threads
  75  *
  76  * \param data       pointer to thread data
  77  */
  78 void ddekit_thread_set_my_data(void *data);
  79
  80 /** Sleep for some miliseconds.
  81  *
  82  * \ingroup DDEKit_threads
  83  *
  84  * \param msecs      time to sleep in ms.
  85  */
  86 void ddekit_thread_msleep(unsigned long msecs);
  87
  88 /** Sleep for some microseconds.
  89  *
  90  * \ingroup DDEKit_threads
  91  *
  92  * \param usecs      time to sleep in µs.
  93  */
  94 void ddekit_thread_usleep(unsigned long usecs);
  95
  96 /** Sleep for some nanoseconds.
  97  *
  98  * \ingroup DDEKit_threads
  99  *
 100  * \param usecs      time to sleep in ns.
 101  */
 102 void ddekit_thread_nsleep(unsigned long nsecs);
 103
 104 /** Sleep until a lock becomes unlocked.
 105  *
 106  * \ingroup DDEKit_threads
 107  */
 108 void ddekit_thread_sleep(ddekit_lock_t *lock);
 109
 110 /** Wakeup a waiting thread.
 111  *
 112  * \ingroup DDEKit_threads
 113  */
 114 void ddekit_thread_wakeup(ddekit_thread_t *thread);
 115
 116 /** Terminate a thread
 117  *
 118  * \ingroup DDEKit_threads
 119  */
 120 void ddekit_thread_exit(void) __attribute__((noreturn));
 121
 122 /** Terminate a thread
 123  *
 124  * \ingroup DDEKit_threads
 125  */
 126 void ddekit_thread_terminate(ddekit_thread_t *thread);
 127
 128 /** Get the name, a thread registered with DDEKit.
 129  *
 130  * \ingroup DDEKit_threads
 131  */
 132 const char *ddekit_thread_get_name(ddekit_thread_t *thread);
 133
 134 /** Get unique ID of a DDEKit thread.
 135  *
 136  * \ingroup DDEKit_threads
 137  *
 138  *  DDEKit does not allow direct access to the thread data
 139  *  structure, since this struct contains L4-specific data types.
 140  *  However, applications might want to get some kind of ID related
 141  *  to a ddekit_thread, for instance to use it as a Linux-like PID.
 142  */
 143 int ddekit_thread_get_id(ddekit_thread_t *thread);
 144
 145 /** Hint that this thread is done and may be scheduled somehow.
 146  *
 147  * \ingroup DDEKit_threads
 148  */
 149 void ddekit_thread_schedule(void);
 150
 151 /** Hint that this thread is done and may be scheduled somehow.
 152  *
 153  * \ingroup DDEKit_threads
 154  */
 155 void ddekit_yield(void);
 156
 157 /** Initialize DDEKit thread subsystem.
 158  *
 159  * \ingroup DDEKit_threads
 160  */
 161 void ddekit_init_threads(void);
 162
 163 #endif