aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJouni Malinen <j@w1.fi>2005-06-19 16:53:44 (GMT)
committerJouni Malinen <j@w1.fi>2005-06-19 16:53:44 (GMT)
commit7c4ae276378a883c7624b72afff9551182f79953 (patch)
treee18552d5a8744d34220fee4c0aec6e3fd9274d38
parentc41180142de653ada3e1d871e9febb7e77549d3b (diff)
downloadhostap-history-7c4ae276378a883c7624b72afff9551182f79953.zip
hostap-history-7c4ae276378a883c7624b72afff9551182f79953.tar.gz
hostap-history-7c4ae276378a883c7624b72afff9551182f79953.tar.bz2
Added Doxygen documentation for the event loop interface.
-rw-r--r--hostapd/eloop.c2
-rw-r--r--hostapd/eloop.h123
2 files changed, 105 insertions, 20 deletions
diff --git a/hostapd/eloop.c b/hostapd/eloop.c
index a62b390..39fccb8 100644
--- a/hostapd/eloop.c
+++ b/hostapd/eloop.c
@@ -1,5 +1,5 @@
/*
- * Event loop
+ * Event loop based on select() loop
* Copyright (c) 2002-2005, Jouni Malinen <jkmaline@cc.hut.fi>
*
* This program is free software; you can redistribute it and/or modify
diff --git a/hostapd/eloop.h b/hostapd/eloop.h
index e4a1f26..c57e682 100644
--- a/hostapd/eloop.h
+++ b/hostapd/eloop.h
@@ -10,6 +10,14 @@
* license.
*
* See README and COPYING 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
@@ -18,50 +26,127 @@
/* Magic number for eloop_cancel_timeout() */
#define ELOOP_ALL_CTX (void *) -1
-/* Initialize global event loop data - must be called before any other eloop_*
- * function. user_data is a pointer to global data structure and will be passed
- * as eloop_ctx to signal handlers. */
+/**
+ * eloop_init() - Initialize global event loop data
+ * @user_data: Pointer to global data passed as eloop_ctx to signal handlers
+ *
+ * This function must be called before any other eloop_* function. user_data
+ * can be used to configure a global (to the process) pointer that will be
+ * passed as eloop_ctx parameter to signal handlers.
+ */
void eloop_init(void *user_data);
-/* Register handler for read event */
+/**
+ * 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.
+ */
int eloop_register_read_sock(int sock,
void (*handler)(int sock, void *eloop_ctx,
void *sock_ctx),
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);
-/* Register timeout */
+/**
+ * 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,
void (*handler)(void *eloop_ctx, void *timeout_ctx),
void *eloop_data, void *user_data);
-/* Cancel timeouts matching <handler,eloop_data,user_data>.
- * ELOOP_ALL_CTX can be used as a wildcard for cancelling all timeouts
- * regardless of eloop_data/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(void (*handler)(void *eloop_ctx, void *sock_ctx),
void *eloop_data, void *user_data);
-/* Register handler for signal.
- * Note: signals are 'global' events and there is no local eloop_data pointer
- * like with other handlers. The (global) pointer given to eloop_init() will be
- * used as eloop_ctx for signal handlers. */
-int eloop_register_signal(int sock,
+/**
+ * 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 calback 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.
+ *
+ * Signals are 'global' events and there is no local eloop_data pointer like
+ * with other handlers. The global user_data pointer registered with
+ * eloop_init() will be used as eloop_ctx for signal handlers.
+ */
+int eloop_register_signal(int sig,
void (*handler)(int sig, void *eloop_ctx,
void *signal_ctx),
void *user_data);
-/* Start event loop and continue running as long as there are any registered
- * event handlers. */
+/**
+ * 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);
-/* Terminate event loop even if there are registered events. */
+/**
+ * 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);
-/* Free any reserved resources. After calling eloop_destoy(), other eloop_*
- * functions must not be called before re-running eloop_init(). */
+/**
+ * eloop_destroy - Free any resources allocated for the event loop
+ *
+ * After calling eloop_destoy(), other eloop_* functions must not be called
+ * before re-running eloop_init().
+ */
void eloop_destroy(void);
-/* Check whether event loop has been terminated. */
+/**
+ * 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);
#endif /* ELOOP_H */