.TH "event2/thread.h" 3 "Tue Jan 31 2017" "libevent" \" -*- nroff -*-
.ad l
.nh
.SH NAME
event2/thread.h \- Functions for multi-threaded applications using Libevent\&.
.SH SYNOPSIS
.br
.PP
\fC#include <event2/visibility\&.h>\fP
.br
\fC#include <event2/event\-config\&.h>\fP
.br
.SS "Data Structures"
.in +1c
.ti -1c
.RI "struct \fBevthread_condition_callbacks\fP"
.br
.RI "\fIThis structure describes the interface a threading library uses for condition variables\&. \fP"
.ti -1c
.RI "struct \fBevthread_lock_callbacks\fP"
.br
.RI "\fIThis structure describes the interface a threading library uses for locking\&. \fP"
.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 "\fIDefined if Libevent was built with support for \fBevthread_use_pthreads()\fP \fP"
.ti -1c
.RI "#define \fBEVTHREAD_USE_WINDOWS_THREADS_IMPLEMENTED\fP 1"
.br
.RI "\fIDefined if Libevent was built with support for \fBevthread_use_windows_threads()\fP \fP"
.in -1c
.PP
.RI "\fBFlags passed to lock functions\fP"
.br
.in +1c
.in +1c
.ti -1c
.RI "#define \fBEVTHREAD_WRITE\fP 0x04"
.br
.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"
.ti -1c
.RI "#define \fBEVTHREAD_READ\fP 0x08"
.br
.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"
.ti -1c
.RI "#define \fBEVTHREAD_TRY\fP 0x10"
.br
.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"
.in -1c
.in -1c
.PP
.RI "\fBTypes of locks\fP"
.br
.in +1c
.in +1c
.ti -1c
.RI "#define \fBEVTHREAD_LOCKTYPE_RECURSIVE\fP 1"
.br
.RI "\fIA recursive lock is one that can be acquired multiple times at once by the same thread\&. \fP"
.ti -1c
.RI "#define \fBEVTHREAD_LOCKTYPE_READWRITE\fP 2"
.br
.in -1c
.in -1c
.SS "Functions"
.in +1c
.ti -1c
.RI "EVENT2_EXPORT_SYMBOL void \fBevthread_enable_lock_debugging\fP (void)"
.br
.RI "\fIEnable debugging wrappers around the current lock callbacks\&. \fP"
.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 "\fIMake sure it's safe to tell an event base to wake up from another thread or a signal handler\&. \fP"
.ti -1c
.RI "EVENT2_EXPORT_SYMBOL int \fBevthread_set_condition_callbacks\fP (const struct \fBevthread_condition_callbacks\fP *)"
.br
.RI "\fISets a group of functions that Libevent should use for condition variables\&. \fP"
.ti -1c
.RI "EVENT2_EXPORT_SYMBOL void \fBevthread_set_id_callback\fP (unsigned long(*id_fn)(void))"
.br
.RI "\fISets the function for determining the thread id\&. \fP"
.ti -1c
.RI "EVENT2_EXPORT_SYMBOL int \fBevthread_set_lock_callbacks\fP (const struct \fBevthread_lock_callbacks\fP *)"
.br
.RI "\fISets a group of functions that Libevent should use for locking\&. \fP"
.ti -1c
.RI "EVENT2_EXPORT_SYMBOL int \fBevthread_use_pthreads\fP (void)"
.br
.RI "\fISets up Libevent for use with Pthreads locking and thread ID functions\&. \fP"
.ti -1c
.RI "EVENT2_EXPORT_SYMBOL int \fBevthread_use_windows_threads\fP (void)"
.br
.RI "\fISets up Libevent for use with Windows builtin locking and thread ID functions\&. \fP"
.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\&.
.SS "#define EVTHREAD_READ 0x08"
.PP
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\&.
.SS "#define EVTHREAD_TRY 0x10"
.PP
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\&.
.SS "#define EVTHREAD_WRITE 0x04"
.PP
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\&.
.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(*)(void) id_fn)"
.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 from the source code\&.