Functions for multi-threaded applications using Libevent. More...

#include <event2/visibility.h>
#include <event2/event-config.h>

Data Structures
struct	evthread_condition_callbacks
	This structure describes the interface a threading library uses for condition variables. More...

struct	evthread_lock_callbacks
	This structure describes the interface a threading library uses for locking. More...

Macros
#define	EVTHREAD_CONDITION_API_VERSION 1

#define	EVTHREAD_LOCK_API_VERSION 1

#define	EVTHREAD_PTHREAD_PRIO_INHERIT 0x01

#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_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.

#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.

Types of locks
#define	EVTHREAD_LOCKTYPE_READWRITE 2

#define	EVTHREAD_LOCKTYPE_RECURSIVE 1
	A recursive lock is one that can be acquired multiple times at once by the same thread. More...

Functions
EVENT2_EXPORT_SYMBOL void	evthread_enable_lock_debugging (void)
	Enable debugging wrappers around the current lock callbacks. More...

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. More...

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. More...

EVENT2_EXPORT_SYMBOL void	evthread_set_id_callback (unsigned long(*id_fn)(void))
	Sets the function for determining the thread id. More...

EVENT2_EXPORT_SYMBOL int	evthread_set_lock_callbacks (const struct evthread_lock_callbacks *)
	Sets a group of functions that Libevent should use for locking. More...

EVENT2_EXPORT_SYMBOL int	evthread_use_pthreads (void)
	Sets up Libevent for use with Pthreads locking and thread ID functions. More...

EVENT2_EXPORT_SYMBOL int	evthread_use_pthreads_with_flags (int flags)
	Sets up Libevent for use with Pthreads locking and thread ID functions. More...

EVENT2_EXPORT_SYMBOL int	evthread_use_windows_threads (void)
	Sets up Libevent for use with Windows builtin locking and thread ID functions. More...

Detailed Description

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 evthread_use_windows_threads() or evthread_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().

Macro Definition Documentation

◆ EVTHREAD_LOCKTYPE_RECURSIVE

#define EVTHREAD_LOCKTYPE_RECURSIVE 1

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.

Function Documentation

◆ evthread_enable_lock_debugging()

EVENT2_EXPORT_SYMBOL void evthread_enable_lock_debugging ( void )

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.

◆ evthread_make_base_notifiable()

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.

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.

◆ evthread_set_condition_callbacks()

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.

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.

◆ evthread_set_id_callback()

EVENT2_EXPORT_SYMBOL void evthread_set_id_callback ( unsigned long(*)(void) id_fn )

Sets the function for determining the thread id.

Parameters

id_fn the identify function Libevent should invoke to determine the identity of a thread.

◆ evthread_set_lock_callbacks()

EVENT2_EXPORT_SYMBOL int evthread_set_lock_callbacks ( const struct evthread_lock_callbacks * )

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.

◆ evthread_use_pthreads()

EVENT2_EXPORT_SYMBOL int evthread_use_pthreads ( void )

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.

◆ evthread_use_pthreads_with_flags()

EVENT2_EXPORT_SYMBOL int evthread_use_pthreads_with_flags ( int flags )

Sets up Libevent for use with Pthreads locking and thread ID functions.

Use evthread_use_pthreads_with_flags() to use Pthreads locking, taking the specified flags under consideration.

Parameters

flags the flags to apply when setting up Pthreads locking.

See also: EVTHREAD_PTHREAD_*

Returns: 0 on success, -1 on failure.

◆ evthread_use_windows_threads()

EVENT2_EXPORT_SYMBOL int evthread_use_windows_threads ( void )

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.

Data Structures

Macros

Functions