evthread - Functions for multi-threaded applications using Libevent.
#include <event2/thread.h>
#include <event2/visibility.h>
#include <event2/event-config.h>
struct evthread_condition_callbacks
This structure describes the interface a threading library uses for condition
variables. struct evthread_lock_callbacks
This structure describes the interface a threading library uses for locking.
#define EVTHREAD_CONDITION_API_VERSION 1
#define EVTHREAD_LOCK_API_VERSION 1
#define EVTHREAD_USE_PTHREADS_IMPLEMENTED 1
Defined if Libevent was built with support for
evthread_use_pthreads() #define
EVTHREAD_USE_WINDOWS_THREADS_IMPLEMENTED 1
Defined if Libevent was built with support for
evthread_use_windows_threads()
Flags passed to lock functions
#define EVTHREAD_WRITE 0x04
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.
#define EVTHREAD_READ 0x08
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.
#define EVTHREAD_TRY 0x10
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.
Types of locks
#define EVTHREAD_LOCKTYPE_RECURSIVE 1
A recursive lock is one that can be acquired multiple times at once by the
same thread. #define EVTHREAD_LOCKTYPE_READWRITE 2
EVENT2_EXPORT_SYMBOL void evthread_enable_lock_debugging (void)
Enable debugging wrappers around the current lock callbacks.
EVENT2_EXPORT_SYMBOL void evthread_enable_lock_debuging (void)
EVENT2_EXPORT_SYMBOL int evthread_make_base_notifiable (struct
event_base *base)
Make sure it's safe to tell an event base to wake up from another thread or a
signal handler. EVENT2_EXPORT_SYMBOL int
evthread_set_condition_callbacks (const struct
evthread_condition_callbacks *)
Sets a group of functions that Libevent should use for condition variables.
EVENT2_EXPORT_SYMBOL void evthread_set_id_callback (unsigned
long(*id_fn)(void))
Sets the function for determining the thread id. EVENT2_EXPORT_SYMBOL
int evthread_set_lock_callbacks (const struct
evthread_lock_callbacks *)
Sets a group of functions that Libevent should use for locking.
EVENT2_EXPORT_SYMBOL int evthread_use_pthreads (void)
Sets up Libevent for use with Pthreads locking and thread ID functions.
EVENT2_EXPORT_SYMBOL int evthread_use_windows_threads (void)
Sets up Libevent for use with Windows builtin locking and thread ID
functions.
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.
Like the memory-management function hooks, all of the threading
functions must be set up before an event_base is created if
you want the base to use them.
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 evthread_set_lock_callbacks() and
evthread_set_condition_callbacks().
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.
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.
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.
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.
Enable debugging wrappers around the current lock callbacks. If Libevent makes
one of several common locking errors, exit with an assertion failure.
If you're going to call this function, you must do so before any
locks are allocated.
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.
Returns:
0 on success, -1 on failure.
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 evthread_condition_callbacks.
Note that if you're using Windows or the Pthreads threading
library, you probably shouldn't call this function; instead, use
evthread_use_windows_threads() or evthread_use_pthreads() if
you can.
Sets the function for determining the thread id.
Parameters:
base the event base for which to set the id
function
id_fn the identify function Libevent should invoke to determine the
identity of a thread.
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 evthread_lock_callbacks.
Note that if you're using Windows or the Pthreads threading
library, you probably shouldn't call this function; instead, use
evthread_use_windows_threads() or evthread_use_posix_threads() if you
can.
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.
Returns:
0 on success, -1 on failure.
Sets up Libevent for use with Windows builtin locking and thread ID functions.
Unavailable if Libevent is not built for Windows.
Returns:
0 on success, -1 on failure.
Generated automatically by Doxygen for libevent from the source code.