external/bsd/libevent/man/thread.h.3

   1 .TH "event2/thread.h" 3 "Tue Jan 27 2015" "libevent" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 event2/thread.h \-
   6 .PP
   7 Functions for multi-threaded applications using Libevent\&.
   8
   9 .SH SYNOPSIS
  10 .br
  11 .PP
  12 \fC#include <event2/event-config\&.h>\fP
  13 .br
  14
  15 .SS "Data Structures"
  16
  17 .in +1c
  18 .ti -1c
  19 .RI "struct \fBevthread_condition_callbacks\fP"
  20 .br
  21 .RI "\fIThis structure describes the interface a threading library uses for condition variables\&. \fP"
  22 .ti -1c
  23 .RI "struct \fBevthread_lock_callbacks\fP"
  24 .br
  25 .RI "\fIThis structure describes the interface a threading library uses for locking\&. \fP"
  26 .in -1c
  27 .SS "Macros"
  28
  29 .in +1c
  30 .ti -1c
  31 .RI "#define \fBEVTHREAD_CONDITION_API_VERSION\fP   1"
  32 .br
  33 .ti -1c
  34 .RI "#define \fBEVTHREAD_LOCK_API_VERSION\fP   1"
  35 .br
  36 .ti -1c
  37 .RI "#define \fBEVTHREAD_USE_PTHREADS_IMPLEMENTED\fP   1"
  38 .br
  39 .RI "\fIDefined if Libevent was built with support for \fBevthread_use_pthreads()\fP \fP"
  40 .ti -1c
  41 .RI "#define \fBEVTHREAD_USE_WINDOWS_THREADS_IMPLEMENTED\fP   1"
  42 .br
  43 .RI "\fIDefined if Libevent was built with support for \fBevthread_use_windows_threads()\fP \fP"
  44 .in -1c
  45 .PP
  46 .RI "\fBFlags passed to lock functions\fP"
  47 .br
  48
  49 .in +1c
  50 .in +1c
  51 .ti -1c
  52 .RI "#define \fBEVTHREAD_WRITE\fP   0x04"
  53 .br
  54 .RI "\fIA flag passed to a locking callback when the lock was allocated as a read-write lock, and we want to acquire or release the lock for writing\&. \fP"
  55 .ti -1c
  56 .RI "#define \fBEVTHREAD_READ\fP   0x08"
  57 .br
  58 .RI "\fIA flag passed to a locking callback when the lock was allocated as a read-write lock, and we want to acquire or release the lock for reading\&. \fP"
  59 .ti -1c
  60 .RI "#define \fBEVTHREAD_TRY\fP   0x10"
  61 .br
  62 .RI "\fIA flag passed to a locking callback when we don't want to block waiting for the lock; if we can't get the lock immediately, we will instead return nonzero from the locking callback\&. \fP"
  63 .in -1c
  64 .in -1c
  65 .PP
  66 .RI "\fBTypes of locks\fP"
  67 .br
  68
  69 .in +1c
  70 .in +1c
  71 .ti -1c
  72 .RI "#define \fBEVTHREAD_LOCKTYPE_RECURSIVE\fP   1"
  73 .br
  74 .RI "\fIA recursive lock is one that can be acquired multiple times at once by the same thread\&. \fP"
  75 .ti -1c
  76 .RI "#define \fBEVTHREAD_LOCKTYPE_READWRITE\fP   2"
  77 .br
  78 .in -1c
  79 .in -1c
  80 .SS "Functions"
  81
  82 .in +1c
  83 .ti -1c
  84 .RI "void \fBevthread_enable_lock_debuging\fP (void)"
  85 .br
  86 .RI "\fIEnable debugging wrappers around the current lock callbacks\&. \fP"
  87 .ti -1c
  88 .RI "int \fBevthread_make_base_notifiable\fP (struct \fBevent_base\fP *base)"
  89 .br
  90 .RI "\fIMake sure it's safe to tell an event base to wake up from another thread or a signal handler\&. \fP"
  91 .ti -1c
  92 .RI "int \fBevthread_set_condition_callbacks\fP (const struct \fBevthread_condition_callbacks\fP *)"
  93 .br
  94 .RI "\fISets a group of functions that Libevent should use for condition variables\&. \fP"
  95 .ti -1c
  96 .RI "void \fBevthread_set_id_callback\fP (unsigned long(*id_fn)(void))"
  97 .br
  98 .RI "\fISets the function for determining the thread id\&. \fP"
  99 .ti -1c
 100 .RI "int \fBevthread_set_lock_callbacks\fP (const struct \fBevthread_lock_callbacks\fP *)"
 101 .br
 102 .RI "\fISets a group of functions that Libevent should use for locking\&. \fP"
 103 .ti -1c
 104 .RI "int \fBevthread_use_pthreads\fP (void)"
 105 .br
 106 .RI "\fISets up Libevent for use with Pthreads locking and thread ID functions\&. \fP"
 107 .ti -1c
 108 .RI "int \fBevthread_use_windows_threads\fP (void)"
 109 .br
 110 .RI "\fISets up Libevent for use with Windows builtin locking and thread ID functions\&. \fP"
 111 .in -1c
 112 .SH "Detailed Description"
 113 .PP
 114 Functions for multi-threaded applications using Libevent\&.
 115
 116 When using a multi-threaded application in which multiple threads add and delete events from a single event base, Libevent needs to lock its data structures\&.
 117 .PP
 118 Like the memory-management function hooks, all of the threading functions \fImust\fP be set up before an \fBevent_base\fP is created if you want the base to use them\&.
 119 .PP
 120 Most programs will either be using Windows threads or Posix threads\&. You can configure Libevent to use one of these event_use_windows_threads() or event_use_pthreads() respectively\&. If you're using another threading library, you'll need to configure threading functions manually using \fBevthread_set_lock_callbacks()\fP and \fBevthread_set_condition_callbacks()\fP\&.
 121 .SH "Macro Definition Documentation"
 122 .PP
 123 .SS "#define EVTHREAD_LOCKTYPE_RECURSIVE   1"
 124
 125 .PP
 126 A recursive lock is one that can be acquired multiple times at once by the same thread\&. No other process can allocate the lock until the thread that has been holding it has unlocked it as many times as it locked it\&.
 127 .SS "#define EVTHREAD_READ   0x08"
 128
 129 .PP
 130 A flag passed to a locking callback when the lock was allocated as a read-write lock, and we want to acquire or release the lock for reading\&.
 131 .SS "#define EVTHREAD_TRY   0x10"
 132
 133 .PP
 134 A flag passed to a locking callback when we don't want to block waiting for the lock; if we can't get the lock immediately, we will instead return nonzero from the locking callback\&.
 135 .SS "#define EVTHREAD_WRITE   0x04"
 136
 137 .PP
 138 A flag passed to a locking callback when the lock was allocated as a read-write lock, and we want to acquire or release the lock for writing\&.
 139 .SH "Function Documentation"
 140 .PP
 141 .SS "void evthread_enable_lock_debuging (void)"
 142
 143 .PP
 144 Enable debugging wrappers around the current lock callbacks\&. If Libevent makes one of several common locking errors, exit with an assertion failure\&.
 145 .PP
 146 If you're going to call this function, you must do so before any locks are allocated\&.
 147 .SS "int evthread_make_base_notifiable (struct \fBevent_base\fP *base)"
 148
 149 .PP
 150 Make sure it's safe to tell an event base to wake up from another thread or a signal handler\&.
 151 .PP
 152 \fBReturns:\fP
 153 .RS 4
 154 0 on success, -1 on failure\&.
 155 .RE
 156 .PP
 157
 158 .SS "int evthread_set_condition_callbacks (const struct \fBevthread_condition_callbacks\fP *)"
 159
 160 .PP
 161 Sets a group of functions that Libevent should use for condition variables\&. For full information on the required callback API, see the documentation for the individual members of \fBevthread_condition_callbacks\fP\&.
 162 .PP
 163 Note that if you're using Windows or the Pthreads threading library, you probably shouldn't call this function; instead, use \fBevthread_use_windows_threads()\fP or \fBevthread_use_pthreads()\fP if you can\&.
 164 .SS "void evthread_set_id_callback (unsigned long(*)(void)id_fn)"
 165
 166 .PP
 167 Sets the function for determining the thread id\&.
 168 .PP
 169 \fBParameters:\fP
 170 .RS 4
 171 \fIbase\fP the event base for which to set the id function
 172 .br
 173 \fIid_fn\fP the identify function Libevent should invoke to determine the identity of a thread\&.
 174 .RE
 175 .PP
 176
 177 .SS "int evthread_set_lock_callbacks (const struct \fBevthread_lock_callbacks\fP *)"
 178
 179 .PP
 180 Sets a group of functions that Libevent should use for locking\&. For full information on the required callback API, see the documentation for the individual members of \fBevthread_lock_callbacks\fP\&.
 181 .PP
 182 Note that if you're using Windows or the Pthreads threading library, you probably shouldn't call this function; instead, use \fBevthread_use_windows_threads()\fP or evthread_use_posix_threads() if you can\&.
 183 .SS "int evthread_use_pthreads (void)"
 184
 185 .PP
 186 Sets up Libevent for use with Pthreads locking and thread ID functions\&. Unavailable if Libevent is not build for use with pthreads\&. Requires libraries to link against Libevent_pthreads as well as Libevent\&.
 187 .PP
 188 \fBReturns:\fP
 189 .RS 4
 190 0 on success, -1 on failure\&.
 191 .RE
 192 .PP
 193
 194 .SS "int evthread_use_windows_threads (void)"
 195
 196 .PP
 197 Sets up Libevent for use with Windows builtin locking and thread ID functions\&. Unavailable if Libevent is not built for Windows\&.
 198 .PP
 199 \fBReturns:\fP
 200 .RS 4
 201 0 on success, -1 on failure\&.
 202 .RE
 203 .PP
 204
 205 .SH "Author"
 206 .PP
 207 Generated automatically by Doxygen for libevent from the source code\&.