.TH "event2/thread.h" 3 "libevent-2.1.13-stable" \" -*- nroff -*- .ad l .nh .SH NAME event2/thread.h \- Functions for multi-threaded applications using Libevent\&. .SH SYNOPSIS .br .PP \fR#include \fP .br \fR#include \fP .br .SS "Data Structures" .in +1c .ti -1c .RI "struct \fBevthread_condition_callbacks\fP" .br .RI "This structure describes the interface a threading library uses for condition variables\&. " .ti -1c .RI "struct \fBevthread_lock_callbacks\fP" .br .RI "This structure describes the interface a threading library uses for locking\&. " .in -1c .SS "Macros" .in +1c .ti -1c .RI "#define \fBEVTHREAD_CONDITION_API_VERSION\fP 1" .br .ti -1c .RI "#define \fBEVTHREAD_LOCK_API_VERSION\fP 1" .br .ti -1c .RI "#define \fBEVTHREAD_USE_PTHREADS_IMPLEMENTED\fP 1" .br .RI "Defined if Libevent was built with support for \fBevthread_use_pthreads()\fP\&. " .ti -1c .RI "#define \fBEVTHREAD_USE_WINDOWS_THREADS_IMPLEMENTED\fP 1" .br .RI "Defined if Libevent was built with support for \fBevthread_use_windows_threads()\fP\&. " .in -1c .PP .RI "\fBFlags passed to lock functions\fP" .br .in +1c .in +1c .ti -1c .RI "#define \fBEVTHREAD_READ\fP 0x08" .br .RI "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\&. " .ti -1c .RI "#define \fBEVTHREAD_TRY\fP 0x10" .br .RI "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\&. " .ti -1c .RI "#define \fBEVTHREAD_WRITE\fP 0x04" .br .RI "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\&. " .in -1c .in -1c .PP .RI "\fBTypes of locks\fP" .br .in +1c .in +1c .ti -1c .RI "#define \fBEVTHREAD_LOCKTYPE_READWRITE\fP 2" .br .ti -1c .RI "#define \fBEVTHREAD_LOCKTYPE_RECURSIVE\fP 1" .br .RI "A recursive lock is one that can be acquired multiple times at once by the same thread\&. " .in -1c .in -1c .SS "Functions" .in +1c .ti -1c .RI "EVENT2_EXPORT_SYMBOL void \fBevthread_enable_lock_debugging\fP (void)" .br .RI "Enable debugging wrappers around the current lock callbacks\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL void \fBevthread_enable_lock_debuging\fP (void)" .br .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevthread_make_base_notifiable\fP (struct \fBevent_base\fP *base)" .br .RI "Make sure it's safe to tell an event base to wake up from another thread or a signal handler\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevthread_set_condition_callbacks\fP (const struct \fBevthread_condition_callbacks\fP *)" .br .RI "Sets a group of functions that Libevent should use for condition variables\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL void \fBevthread_set_id_callback\fP (unsigned long(*id_fn)(void))" .br .RI "Sets the function for determining the thread id\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevthread_set_lock_callbacks\fP (const struct \fBevthread_lock_callbacks\fP *)" .br .RI "Sets a group of functions that Libevent should use for locking\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevthread_use_pthreads\fP (void)" .br .RI "Sets up Libevent for use with Pthreads locking and thread ID functions\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevthread_use_windows_threads\fP (void)" .br .RI "Sets up Libevent for use with Windows builtin locking and thread ID functions\&. " .in -1c .SH "Detailed Description" .PP Functions for multi-threaded applications using Libevent\&. 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\&. .PP 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\&. .PP 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\&. .SH "Macro Definition Documentation" .PP .SS "#define EVTHREAD_LOCKTYPE_RECURSIVE 1" .PP 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\&. .SH "Function Documentation" .PP .SS "EVENT2_EXPORT_SYMBOL void evthread_enable_lock_debugging (void )" .PP Enable debugging wrappers around the current lock callbacks\&. If Libevent makes one of several common locking errors, exit with an assertion failure\&. .PP If you're going to call this function, you must do so before any locks are allocated\&. .SS "EVENT2_EXPORT_SYMBOL int evthread_make_base_notifiable (struct \fBevent_base\fP * base)" .PP Make sure it's safe to tell an event base to wake up from another thread or a signal handler\&. You shouldn't need to call this by hand; configuring the base with thread support should be necessary and sufficient\&. .PP \fBReturns\fP .RS 4 0 on success, -1 on failure\&. .RE .PP .SS "EVENT2_EXPORT_SYMBOL int evthread_set_condition_callbacks (const struct \fBevthread_condition_callbacks\fP * )" .PP 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\&. .PP 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\&. .SS "EVENT2_EXPORT_SYMBOL void evthread_set_id_callback (unsigned long(* id_fn )(void))" .PP Sets the function for determining the thread id\&. .PP \fBParameters\fP .RS 4 \fIbase\fP the event base for which to set the id function .br \fIid_fn\fP the identify function Libevent should invoke to determine the identity of a thread\&. .RE .PP .SS "EVENT2_EXPORT_SYMBOL int evthread_set_lock_callbacks (const struct \fBevthread_lock_callbacks\fP * )" .PP 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\&. .PP 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\&. .SS "EVENT2_EXPORT_SYMBOL int evthread_use_pthreads (void )" .PP 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\&. .PP \fBReturns\fP .RS 4 0 on success, -1 on failure\&. .RE .PP .SS "EVENT2_EXPORT_SYMBOL int evthread_use_windows_threads (void )" .PP Sets up Libevent for use with Windows builtin locking and thread ID functions\&. Unavailable if Libevent is not built for Windows\&. .PP \fBReturns\fP .RS 4 0 on success, -1 on failure\&. .RE .PP .SH "Author" .PP Generated automatically by Doxygen for libevent-2\&.1\&.13-stable from the source code\&.