blob: 04ee6d1837b63e92ceef4448975eceeaa5fb073c [file] [log] [blame]
/*
* Event loop
* Copyright (c) 2002-2006, Jouni Malinen <j@w1.fi>
*
* This software may be distributed under the terms of the BSD license.
* See README for more details.
*
* This file defines an event loop interface that supports processing events
* from registered timeouts (i.e., do something after N seconds), sockets
* (e.g., a new packet available for reading), and signals. eloop.c is an
* implementation of this interface using select() and sockets. This is
* suitable for most UNIX/POSIX systems. When porting to other operating
* systems, it may be necessary to replace that implementation with OS specific
* mechanisms.
*/
#ifndef ELOOP_H
#define ELOOP_H
/**
* ELOOP_ALL_CTX - eloop_cancel_timeout() magic number to match all timeouts
*/
#define ELOOP_ALL_CTX (void *) -1
/**
* eloop_event_type - eloop socket event type for eloop_register_sock()
* @EVENT_TYPE_READ: Socket has data available for reading
* @EVENT_TYPE_WRITE: Socket has room for new data to be written
* @EVENT_TYPE_EXCEPTION: An exception has been reported
*/
typedef enum {
EVENT_TYPE_READ = 0,
EVENT_TYPE_WRITE,
EVENT_TYPE_EXCEPTION
} eloop_event_type;
/**
* eloop_sock_handler - eloop socket event callback type
* @sock: File descriptor number for the socket
* @eloop_ctx: Registered callback context data (eloop_data)
* @sock_ctx: Registered callback context data (user_data)
*/
typedef void (*eloop_sock_handler)(int sock, void *eloop_ctx, void *sock_ctx);
/**
* eloop_event_handler - eloop generic event callback type
* @eloop_ctx: Registered callback context data (eloop_data)
* @user_ctx: Registered callback context data (user_data)
*/
typedef void (*eloop_event_handler)(void *eloop_ctx, void *user_ctx);
/**
* eloop_timeout_handler - eloop timeout event callback type
* @eloop_ctx: Registered callback context data (eloop_data)
* @user_ctx: Registered callback context data (user_data)
*/
typedef void (*eloop_timeout_handler)(void *eloop_ctx, void *user_ctx);
/**
* eloop_signal_handler - eloop signal event callback type
* @sig: Signal number
* @signal_ctx: Registered callback context data (user_data from
* eloop_register_signal(), eloop_register_signal_terminate(), or
* eloop_register_signal_reconfig() call)
*/
typedef void (*eloop_signal_handler)(int sig, void *signal_ctx);
/**
* eloop_init() - Initialize global event loop data
* Returns: 0 on success, -1 on failure
*
* This function must be called before any other eloop_* function.
*/
int eloop_init(void);
/**
* eloop_register_read_sock - Register handler for read events
* @sock: File descriptor number for the socket
* @handler: Callback function to be called when data is available for reading
* @eloop_data: Callback context data (eloop_ctx)
* @user_data: Callback context data (sock_ctx)
* Returns: 0 on success, -1 on failure
*
* Register a read socket notifier for the given file descriptor. The handler
* function will be called whenever data is available for reading from the
* socket. The handler function is responsible for clearing the event after
* having processed it in order to avoid eloop from calling the handler again
* for the same event.
*/
int eloop_register_read_sock(int sock, eloop_sock_handler handler,
void *eloop_data, void *user_data);
/**
* eloop_unregister_read_sock - Unregister handler for read events
* @sock: File descriptor number for the socket
*
* Unregister a read socket notifier that was previously registered with
* eloop_register_read_sock().
*/
void eloop_unregister_read_sock(int sock);
/**
* eloop_register_sock - Register handler for socket events
* @sock: File descriptor number for the socket
* @type: Type of event to wait for
* @handler: Callback function to be called when the event is triggered
* @eloop_data: Callback context data (eloop_ctx)
* @user_data: Callback context data (sock_ctx)
* Returns: 0 on success, -1 on failure
*
* Register an event notifier for the given socket's file descriptor. The
* handler function will be called whenever the that event is triggered for the
* socket. The handler function is responsible for clearing the event after
* having processed it in order to avoid eloop from calling the handler again
* for the same event.
*/
int eloop_register_sock(int sock, eloop_event_type type,
eloop_sock_handler handler,
void *eloop_data, void *user_data);
/**
* eloop_unregister_sock - Unregister handler for socket events
* @sock: File descriptor number for the socket
* @type: Type of event for which sock was registered
*
* Unregister a socket event notifier that was previously registered with
* eloop_register_sock().
*/
void eloop_unregister_sock(int sock, eloop_event_type type);
/**
* eloop_register_event - Register handler for generic events
* @event: Event to wait (eloop implementation specific)
* @event_size: Size of event data
* @handler: Callback function to be called when event is triggered
* @eloop_data: Callback context data (eloop_data)
* @user_data: Callback context data (user_data)
* Returns: 0 on success, -1 on failure
*
* Register an event handler for the given event. This function is used to
* register eloop implementation specific events which are mainly targeted for
* operating system specific code (driver interface and l2_packet) since the
* portable code will not be able to use such an OS-specific call. The handler
* function will be called whenever the event is triggered. The handler
* function is responsible for clearing the event after having processed it in
* order to avoid eloop from calling the handler again for the same event.
*
* In case of Windows implementation (eloop_win.c), event pointer is of HANDLE
* type, i.e., void*. The callers are likely to have 'HANDLE h' type variable,
* and they would call this function with eloop_register_event(h, sizeof(h),
* ...).
*/
int eloop_register_event(void *event, size_t event_size,
eloop_event_handler handler,
void *eloop_data, void *user_data);
/**
* eloop_unregister_event - Unregister handler for a generic event
* @event: Event to cancel (eloop implementation specific)
* @event_size: Size of event data
*
* Unregister a generic event notifier that was previously registered with
* eloop_register_event().
*/
void eloop_unregister_event(void *event, size_t event_size);
/**
* eloop_register_timeout - Register timeout
* @secs: Number of seconds to the timeout
* @usecs: Number of microseconds to the timeout
* @handler: Callback function to be called when timeout occurs
* @eloop_data: Callback context data (eloop_ctx)
* @user_data: Callback context data (sock_ctx)
* Returns: 0 on success, -1 on failure
*
* Register a timeout that will cause the handler function to be called after
* given time.
*/
int eloop_register_timeout(unsigned int secs, unsigned int usecs,
eloop_timeout_handler handler,
void *eloop_data, void *user_data);
/**
* eloop_cancel_timeout - Cancel timeouts
* @handler: Matching callback function
* @eloop_data: Matching eloop_data or %ELOOP_ALL_CTX to match all
* @user_data: Matching user_data or %ELOOP_ALL_CTX to match all
* Returns: Number of cancelled timeouts
*
* Cancel matching <handler,eloop_data,user_data> timeouts registered with
* eloop_register_timeout(). ELOOP_ALL_CTX can be used as a wildcard for
* cancelling all timeouts regardless of eloop_data/user_data.
*/
int eloop_cancel_timeout(eloop_timeout_handler handler,
void *eloop_data, void *user_data);
/**
* eloop_cancel_timeout_one - Cancel a single timeout
* @handler: Matching callback function
* @eloop_data: Matching eloop_data
* @user_data: Matching user_data
* @remaining: Time left on the cancelled timer
* Returns: Number of cancelled timeouts
*
* Cancel matching <handler,eloop_data,user_data> timeout registered with
* eloop_register_timeout() and return the remaining time left.
*/
int eloop_cancel_timeout_one(eloop_timeout_handler handler,
void *eloop_data, void *user_data,
struct os_reltime *remaining);
/**
* eloop_is_timeout_registered - Check if a timeout is already registered
* @handler: Matching callback function
* @eloop_data: Matching eloop_data
* @user_data: Matching user_data
* Returns: 1 if the timeout is registered, 0 if the timeout is not registered
*
* Determine if a matching <handler,eloop_data,user_data> timeout is registered
* with eloop_register_timeout().
*/
int eloop_is_timeout_registered(eloop_timeout_handler handler,
void *eloop_data, void *user_data);
/**
* eloop_deplete_timeout - Deplete a timeout that is already registered
* @req_secs: Requested number of seconds to the timeout
* @req_usecs: Requested number of microseconds to the timeout
* @handler: Matching callback function
* @eloop_data: Matching eloop_data
* @user_data: Matching user_data
* Returns: 1 if the timeout is depleted, 0 if no change is made, -1 if no
* timeout matched
*
* Find a registered matching <handler,eloop_data,user_data> timeout. If found,
* deplete the timeout if remaining time is more than the requested time.
*/
int eloop_deplete_timeout(unsigned int req_secs, unsigned int req_usecs,
eloop_timeout_handler handler, void *eloop_data,
void *user_data);
/**
* eloop_replenish_timeout - Replenish a timeout that is already registered
* @req_secs: Requested number of seconds to the timeout
* @req_usecs: Requested number of microseconds to the timeout
* @handler: Matching callback function
* @eloop_data: Matching eloop_data
* @user_data: Matching user_data
* Returns: 1 if the timeout is replenished, 0 if no change is made, -1 if no
* timeout matched
*
* Find a registered matching <handler,eloop_data,user_data> timeout. If found,
* replenish the timeout if remaining time is less than the requested time.
*/
int eloop_replenish_timeout(unsigned int req_secs, unsigned int req_usecs,
eloop_timeout_handler handler, void *eloop_data,
void *user_data);
/**
* eloop_register_signal - Register handler for signals
* @sig: Signal number (e.g., SIGHUP)
* @handler: Callback function to be called when the signal is received
* @user_data: Callback context data (signal_ctx)
* Returns: 0 on success, -1 on failure
*
* Register a callback function that will be called when a signal is received.
* The callback function is actually called only after the system signal
* handler has returned. This means that the normal limits for sighandlers
* (i.e., only "safe functions" allowed) do not apply for the registered
* callback.
*/
int eloop_register_signal(int sig, eloop_signal_handler handler,
void *user_data);
/**
* eloop_register_signal_terminate - Register handler for terminate signals
* @handler: Callback function to be called when the signal is received
* @user_data: Callback context data (signal_ctx)
* Returns: 0 on success, -1 on failure
*
* Register a callback function that will be called when a process termination
* signal is received. The callback function is actually called only after the
* system signal handler has returned. This means that the normal limits for
* sighandlers (i.e., only "safe functions" allowed) do not apply for the
* registered callback.
*
* This function is a more portable version of eloop_register_signal() since
* the knowledge of exact details of the signals is hidden in eloop
* implementation. In case of operating systems using signal(), this function
* registers handlers for SIGINT and SIGTERM.
*/
int eloop_register_signal_terminate(eloop_signal_handler handler,
void *user_data);
/**
* eloop_register_signal_reconfig - Register handler for reconfig signals
* @handler: Callback function to be called when the signal is received
* @user_data: Callback context data (signal_ctx)
* Returns: 0 on success, -1 on failure
*
* Register a callback function that will be called when a reconfiguration /
* hangup signal is received. The callback function is actually called only
* after the system signal handler has returned. This means that the normal
* limits for sighandlers (i.e., only "safe functions" allowed) do not apply
* for the registered callback.
*
* This function is a more portable version of eloop_register_signal() since
* the knowledge of exact details of the signals is hidden in eloop
* implementation. In case of operating systems using signal(), this function
* registers a handler for SIGHUP.
*/
int eloop_register_signal_reconfig(eloop_signal_handler handler,
void *user_data);
/**
* eloop_sock_requeue - Requeue sockets
*
* Requeue sockets after forking because some implementations require this,
* such as epoll and kqueue.
*/
int eloop_sock_requeue(void);
/**
* eloop_run - Start the event loop
*
* Start the event loop and continue running as long as there are any
* registered event handlers. This function is run after event loop has been
* initialized with event_init() and one or more events have been registered.
*/
void eloop_run(void);
/**
* eloop_terminate - Terminate event loop
*
* Terminate event loop even if there are registered events. This can be used
* to request the program to be terminated cleanly.
*/
void eloop_terminate(void);
/**
* eloop_destroy - Free any resources allocated for the event loop
*
* After calling eloop_destroy(), other eloop_* functions must not be called
* before re-running eloop_init().
*/
void eloop_destroy(void);
/**
* eloop_terminated - Check whether event loop has been terminated
* Returns: 1 = event loop terminate, 0 = event loop still running
*
* This function can be used to check whether eloop_terminate() has been called
* to request termination of the event loop. This is normally used to abort
* operations that may still be queued to be run when eloop_terminate() was
* called.
*/
int eloop_terminated(void);
/**
* eloop_wait_for_read_sock - Wait for a single reader
* @sock: File descriptor number for the socket
*
* Do a blocking wait for a single read socket.
*/
void eloop_wait_for_read_sock(int sock);
#endif /* ELOOP_H */