* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
- *
- * $Id$
+ */
+/* @file
+ * @brief Interface and public definitions for event loop.
+ * @version $Id$
*/
#ifndef INCLUDED_config_h
struct Event;
+/** Generic callback for event activity. */
typedef void (*EventCallBack)(struct Event*);
+/** State of a Socket structure. */
enum SocketState {
- SS_CONNECTING, /* Connection in progress on socket */
- SS_LISTENING, /* Socket is a listening socket */
- SS_CONNECTED, /* Socket is a connected socket */
- SS_DATAGRAM, /* Socket is a datagram socket */
- SS_CONNECTDG, /* Socket is a connected datagram socket */
- SS_NOTSOCK /* Socket isn't a socket at all */
+ SS_CONNECTING, /**< Connection in progress on socket */
+ SS_LISTENING, /**< Socket is a listening socket */
+ SS_CONNECTED, /**< Socket is a connected socket */
+ SS_DATAGRAM, /**< Socket is a datagram socket */
+ SS_CONNECTDG, /**< Socket is a connected datagram socket */
+ SS_NOTSOCK /**< Socket isn't a socket at all */
};
+/** Type of a Timer (how its expiration is measured). */
enum TimerType {
- TT_ABSOLUTE, /* timer that runs at a specific time */
- TT_RELATIVE, /* timer that runs so many seconds in the future */
- TT_PERIODIC /* timer that runs periodically */
+ TT_ABSOLUTE, /**< timer that runs at a specific time */
+ TT_RELATIVE, /**< timer that runs so many seconds in the future */
+ TT_PERIODIC /**< timer that runs periodically */
};
+/** Type of event that generated a callback. */
enum EventType {
- ET_READ, /* Readable event detected */
- ET_WRITE, /* Writable event detected */
- ET_ACCEPT, /* Connection can be accepted */
- ET_CONNECT, /* Connection completed */
- ET_EOF, /* End-of-file on connection */
- ET_ERROR, /* Error condition detected */
- ET_SIGNAL, /* A signal was received */
- ET_EXPIRE, /* A timer expired */
- ET_DESTROY /* The generator is being destroyed */
+ ET_READ, /**< Readable event detected */
+ ET_WRITE, /**< Writable event detected */
+ ET_ACCEPT, /**< Connection can be accepted */
+ ET_CONNECT, /**< Connection completed */
+ ET_EOF, /**< End-of-file on connection */
+ ET_ERROR, /**< Error condition detected */
+ ET_SIGNAL, /**< A signal was received */
+ ET_EXPIRE, /**< A timer expired */
+ ET_DESTROY /**< The generator is being destroyed */
};
+/** Common header for event generators. */
struct GenHeader {
- struct GenHeader* gh_next; /* linked list of generators */
- struct GenHeader** gh_prev_p;
+ struct GenHeader* gh_next; /**< linked list of generators */
+ struct GenHeader** gh_prev_p; /**< previous pointer to this generator */
#ifdef IRCD_THREADED
- struct GenHeader* gh_qnext; /* linked list of generators in queue */
- struct GenHeader** gh_qprev_p;
- struct Event* gh_head; /* head of event queue */
- struct Event* gh_tail; /* tail of event queue */
+ struct GenHeader* gh_qnext; /**< linked list of generators in queue */
+ struct GenHeader** gh_qprev_p; /**< previous pointer to this generator */
+ struct Event* gh_head; /**< head of event queue */
+ struct Event* gh_tail; /**< tail of event queue */
#endif
- unsigned int gh_flags; /* generator flags */
- unsigned int gh_ref; /* reference count */
- EventCallBack gh_call; /* generator callback function */
- void* gh_data; /* extra data */
+ unsigned int gh_flags; /**< generator flags */
+ unsigned int gh_ref; /**< reference count */
+ EventCallBack gh_call; /**< generator callback function */
+ void* gh_data; /**< extra data */
union {
- void* ed_ptr; /* engine data == pointer */
- int ed_int; /* engine data == integer */
- } gh_engdata;/* engine data */
+ void* ed_ptr; /**< engine data as pointer */
+ int ed_int; /**< engine data as integer */
+ } gh_engdata;/**< engine data */
};
-#define GEN_DESTROY 0x0001 /* generator is to be destroyed */
-#define GEN_MARKED 0x0002 /* generator is marked for destruction */
-#define GEN_ACTIVE 0x0004 /* generator is active */
-#define GEN_READD 0x0008 /* generator (timer) must be re-added */
-#define GEN_ERROR 0x0010 /* an error occurred on the generator */
+#define GEN_DESTROY 0x0001 /**< generator is to be destroyed */
+#define GEN_MARKED 0x0002 /**< generator is marked for destruction */
+#define GEN_ACTIVE 0x0004 /**< generator is active */
+#define GEN_READD 0x0008 /**< generator (timer) must be re-added */
+#define GEN_ERROR 0x0010 /**< an error occurred on the generator */
+/** Socket event generator.
+ * Note: The socket state overrides the socket event mask; that is, if
+ * it's an SS_CONNECTING socket, the engine selects its own definition
+ * of what that looks like and ignores s_events. s_events is meaningful
+ * only for SS_CONNECTED, SS_DATAGRAM, and SS_CONNECTDG, but may be set
+ * prior to the state transition, if desired.
+ */
struct Socket {
- struct GenHeader s_header; /* generator information */
- enum SocketState s_state; /* state socket's in */
- unsigned int s_events; /* events socket is interested in */
- int s_fd; /* file descriptor for socket */
+ struct GenHeader s_header; /**< generator information */
+ enum SocketState s_state; /**< state socket's in */
+ unsigned int s_events; /**< events socket is interested in */
+ int s_fd; /**< file descriptor for socket */
};
-#define SOCK_EVENT_READABLE 0x0001 /* interested in readable */
-#define SOCK_EVENT_WRITABLE 0x0002 /* interested in writable */
+#define SOCK_EVENT_READABLE 0x0001 /**< interested in readable */
+#define SOCK_EVENT_WRITABLE 0x0002 /**< interested in writable */
+/** Bitmask of possible event interests for a socket. */
#define SOCK_EVENT_MASK (SOCK_EVENT_READABLE | SOCK_EVENT_WRITABLE)
-#define SOCK_ACTION_SET 0x0000 /* set interest set as follows */
-#define SOCK_ACTION_ADD 0x1000 /* add to interest set */
-#define SOCK_ACTION_DEL 0x2000 /* remove from interest set */
+#define SOCK_ACTION_SET 0x0000 /**< set interest set as follows */
+#define SOCK_ACTION_ADD 0x1000 /**< add to interest set */
+#define SOCK_ACTION_DEL 0x2000 /**< remove from interest set */
-#define SOCK_ACTION_MASK 0x3000 /* mask out the actions */
+#define SOCK_ACTION_MASK 0x3000 /**< mask out the actions */
+/** Retrieve state of the Socket \a sock. */
#define s_state(sock) ((sock)->s_state)
+/** Retrieve interest mask of the Socket \a sock. */
#define s_events(sock) ((sock)->s_events)
+/** Retrieve file descriptor of the Socket \a sock. */
#define s_fd(sock) ((sock)->s_fd)
+/** Retrieve user data pointer of the Socket \a sock. */
#define s_data(sock) ((sock)->s_header.gh_data)
+/** Retrieve engine data integer of the Socket \a sock. */
#define s_ed_int(sock) ((sock)->s_header.gh_engdata.ed_int)
+/** Retrieve engine data pointer of the Socket \a sock. */
#define s_ed_ptr(sock) ((sock)->s_header.gh_engdata.ed_ptr)
+/** Retrieve whether the Socket \a sock is active. */
#define s_active(sock) ((sock)->s_header.gh_flags & GEN_ACTIVE)
-/* Note: The socket state overrides the socket event mask; that is, if
- * it's an SS_CONNECTING socket, the engine selects its own definition
- * of what that looks like and ignores s_events. s_events is meaningful
- * only for SS_CONNECTED, SS_DATAGRAM, and SS_CONNECTDG, but may be set
- * prior to the state transition, if desired.
- */
-
+/** Signal event generator. */
struct Signal {
- struct GenHeader sig_header; /* generator information */
- int sig_signal; /* signal number */
+ struct GenHeader sig_header; /**< generator information */
+ int sig_signal; /**< signal number */
};
+/** Retrieve signal number of the Signal \a sig. */
#define sig_signal(sig) ((sig)->sig_signal)
+/** Retrieve user data pointer of the Signal \a sig. */
#define sig_data(sig) ((sig)->sig_header.gh_data)
+/** Retrieve engine data integer of the Signal \a sig. */
#define sig_ed_int(sig) ((sig)->sig_header.gh_engdata.ed_int)
+/** Retrieve engine data pointer of the Signal \a sig. */
#define sig_ed_ptr(sig) ((sig)->sig_header.gh_engdata.ed_ptr)
+/** Retrieve whether the Signal \a sig is active. */
#define sig_active(sig) ((sig)->sig_header.gh_flags & GEN_ACTIVE)
+/** Timer event generator. */
struct Timer {
- struct GenHeader t_header; /* generator information */
- enum TimerType t_type; /* what type of timer this is */
- time_t t_value; /* value timer was added with */
- time_t t_expire; /* time at which timer expires */
+ struct GenHeader t_header; /**< generator information */
+ enum TimerType t_type; /**< what type of timer this is */
+ time_t t_value; /**< value timer was added with */
+ time_t t_expire; /**< time at which timer expires */
};
+/** Retrieve type of the Timer \a tim. */
#define t_type(tim) ((tim)->t_type)
+/** Retrieve interval of the Timer \a tim. */
#define t_value(tim) ((tim)->t_value)
+/** Retrieve expiration time of the Timer \a tim. */
#define t_expire(tim) ((tim)->t_expire)
+/** Retrieve user data pointer of the Timer \a tim. */
#define t_data(tim) ((tim)->t_header.gh_data)
+/** Retrieve engine data integer of the Timer \a tim. */
#define t_ed_int(tim) ((tim)->t_header.gh_engdata.ed_int)
+/** Retrieve engine data pointer of the Timer \a tim. */
#define t_ed_ptr(tim) ((tim)->t_header.gh_engdata.ed_ptr)
+/** Retrieve whether the Timer \a tim is active. */
#define t_active(tim) ((tim)->t_header.gh_flags & GEN_ACTIVE)
+/** Retrieve whether the Timer \a tim is enqueued. */
#define t_onqueue(tim) ((tim)->t_header.gh_prev_p)
+/** Event activity descriptor. */
struct Event {
- struct Event* ev_next; /* linked list of events on queue */
- struct Event** ev_prev_p;
- enum EventType ev_type; /* Event type */
- int ev_data; /* extra data, like errno value */
+ struct Event* ev_next; /**< linked list of events on queue */
+ struct Event** ev_prev_p; /**< previous pointer to this event */
+ enum EventType ev_type; /**< Event type */
+ int ev_data; /**< extra data, like errno value */
union {
- struct GenHeader* gen_header; /* Generator header */
- struct Socket* gen_socket; /* Socket generating event */
- struct Signal* gen_signal; /* Signal generating event */
- struct Timer* gen_timer; /* Timer generating event */
- } ev_gen; /* object generating event */
+ struct GenHeader* gen_header; /**< Generator header */
+ struct Socket* gen_socket; /**< Socket generating event */
+ struct Signal* gen_signal; /**< Signal generating event */
+ struct Timer* gen_timer; /**< Timer generating event */
+ } ev_gen; /**< object generating event */
};
+/** Retrieve the type of the Event \a ev. */
#define ev_type(ev) ((ev)->ev_type)
+/** Retrieve the extra data of the Event \a ev. */
#define ev_data(ev) ((ev)->ev_data)
+/** Retrieve the Socket that generated the Event \a ev. */
#define ev_socket(ev) ((ev)->ev_gen.gen_socket)
+/** Retrieve the Signal that generated the Event \a ev. */
#define ev_signal(ev) ((ev)->ev_gen.gen_signal)
+/** Retrieve the Timer that generated the Event \a ev. */
#define ev_timer(ev) ((ev)->ev_gen.gen_timer)
+/** List of all event generators. */
struct Generators {
- struct Socket* g_socket; /* list of socket generators */
- struct Signal* g_signal; /* list of signal generators */
- struct Timer* g_timer; /* list of timer generators */
+ struct Socket* g_socket; /**< list of socket generators */
+ struct Signal* g_signal; /**< list of signal generators */
+ struct Timer* g_timer; /**< list of timer generators */
};
-/* returns 1 if successfully initialized, 0 if not */
-typedef int (*EngineInit)(int);
+/** Returns 1 if successfully initialized, 0 if not.
+ * @param[in] max_sockets Number of sockets to support.
+ */
+typedef int (*EngineInit)(int max_sockets);
-/* Tell engine about new signal; set to 0 if engine doesn't know signals */
-typedef void (*EngineSignal)(struct Signal*);
+/** Tell engine about new signal.
+ * @param[in] sig Signal event generator to add.
+ */
+typedef void (*EngineSignal)(struct Signal* sig);
-/* Tell engine about new socket */
-typedef int (*EngineAdd)(struct Socket*);
+/** Tell engine about new socket.
+ * @param[in] sock Socket event generator to add.
+ */
+typedef int (*EngineAdd)(struct Socket* sock);
-/* Tell engine about socket's new_state */
-typedef void (*EngineState)(struct Socket*, enum SocketState new_state);
+/** Tell engine about socket's new_state.
+ * @param[in] sock Socket whose state is changing.
+ * @param[in] new_state New state for socket.
+ */
+typedef void (*EngineState)(struct Socket* sock, enum SocketState new_state);
-/* Tell engine about socket's new_events */
-typedef void (*EngineEvents)(struct Socket*, unsigned int new_events);
+/** Tell engine about socket's new event interests.
+ * @param[in] sock Socket whose interest mask is changing.
+ * @param[in] new_events New event mask to set (not SOCK_ACTION_ADD or SOCK_ACTION_DEL).
+ */
+typedef void (*EngineEvents)(struct Socket* sock, unsigned int new_events);
-/* Tell engine a socket's going away */
-typedef void (*EngineDelete)(struct Socket*);
+/** Tell engine a socket is going away.
+ * @param[in] sock Socket being destroyed.
+ */
+typedef void (*EngineDelete)(struct Socket* sock);
-/* The actual event loop */
-typedef void (*EngineLoop)(struct Generators*);
+/** The actual event loop.
+ * @param[in] gens List of event generators.
+ */
+typedef void (*EngineLoop)(struct Generators* gens);
+/** Structure for an event engine to describe itself. */
struct Engine {
- const char* eng_name; /* a name for the engine */
- EngineInit eng_init; /* initialize engine */
- EngineSignal eng_signal; /* express interest in a signal */
- EngineAdd eng_add; /* express interest in a socket */
- EngineState eng_state; /* mention a change in state to engine */
- EngineEvents eng_events; /* express interest in socket events */
- EngineDelete eng_closing; /* socket is being closed */
- EngineLoop eng_loop; /* actual event loop */
+ const char* eng_name; /**< a name for the engine */
+ EngineInit eng_init; /**< initialize engine */
+ EngineSignal eng_signal; /**< express interest in a signal (may be NULL) */
+ EngineAdd eng_add; /**< express interest in a socket */
+ EngineState eng_state; /**< mention a change in state to engine */
+ EngineEvents eng_events; /**< express interest in socket events */
+ EngineDelete eng_closing; /**< socket is being closed */
+ EngineLoop eng_loop; /**< actual event loop */
};
+/** Increment the reference count of \a gen. */
#define gen_ref_inc(gen) (((struct GenHeader*) (gen))->gh_ref++)
+/** Decrement the reference count of \a gen. */
#define gen_ref_dec(gen) \
do { \
struct GenHeader* _gen = (struct GenHeader*) (gen); \
event_generate(ET_DESTROY, _gen, 0); \
} \
} while (0)
+/** Clear the error flag for \a gen. */
#define gen_clear_error(gen) \
(((struct GenHeader*) (gen))->gh_flags &= ~GEN_ERROR)
void timer_del(struct Timer* timer);
void timer_chg(struct Timer* timer, enum TimerType type, time_t value);
void timer_run(void);
+/** Retrieve the next timer's expiration time from Generators \a gen. */
#define timer_next(gen) ((gen)->g_timer ? (gen)->g_timer->t_expire : 0)
void signal_add(struct Signal* signal, EventCallBack call, void* data,
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
- *
- * $Id$
+ */
+/* @file
+ * @brief Implementation of event loop mid-layer.
+ * @version $Id$
*/
#include "config.h"
#include <stdlib.h>
#include <unistd.h>
-#define SIGS_PER_SOCK 10 /* number of signals to process per socket
+#define SIGS_PER_SOCK 10 /**< number of signals to process per socket
readable event */
#ifdef USE_KQUEUE
extern struct Engine engine_kqueue;
#define ENGINE_KQUEUE &engine_kqueue,
#else
+/** Address of kqueue engine (if used). */
#define ENGINE_KQUEUE
#endif /* USE_KQUEUE */
extern struct Engine engine_devpoll;
#define ENGINE_DEVPOLL &engine_devpoll,
#else
+/** Address of /dev/poll engine (if used). */
#define ENGINE_DEVPOLL
#endif /* USE_DEVPOLL */
extern struct Engine engine_epoll;
#define ENGINE_EPOLL &engine_epoll,
#else
+/** Address of epoll engine (if used). */
#define ENGINE_EPOLL
#endif /* USE_EPOLL */
#ifdef USE_POLL
extern struct Engine engine_poll;
+/** Address of fallback (poll) engine. */
#define ENGINE_FALLBACK &engine_poll,
#else
extern struct Engine engine_select;
+/** Address of fallback (select) engine. */
#define ENGINE_FALLBACK &engine_select,
#endif /* USE_POLL */
-/* list of engines to try */
+/** list of engines to try */
static const struct Engine *evEngines[] = {
ENGINE_KQUEUE
ENGINE_EPOLL
0
};
-/* signal routines pipe data */
+/** Signal routines pipe data.
+ * This is used if an engine does not implement signal handling itself
+ * (when Engine::eng_signal is NULL).
+ */
static struct {
- int fd; /* signal routine's fd */
- struct Socket sock; /* and its struct Socket */
+ int fd; /**< signal routine's fd */
+ struct Socket sock; /**< and its struct Socket */
} sigInfo = { -1 };
-/* All the thread info */
+/** All the thread info */
static struct {
- struct Generators gens; /* List of all generators */
- struct Event* events_free; /* struct Event free list */
- unsigned int events_alloc; /* count of allocated struct Events */
- const struct Engine* engine; /* core engine being used */
+ struct Generators gens; /**< List of all generators */
+ struct Event* events_free; /**< struct Event free list */
+ unsigned int events_alloc; /**< count of allocated struct Events */
+ const struct Engine* engine; /**< core engine being used */
#ifdef IRCD_THREADED
- struct GenHeader* genq_head; /* head of generator event queue */
- struct GenHeader* genq_tail; /* tail of generator event queue */
- unsigned int genq_count; /* count of generators on queue */
+ struct GenHeader* genq_head; /**< head of generator event queue */
+ struct GenHeader* genq_tail; /**< tail of generator event queue */
+ unsigned int genq_count; /**< count of generators on queue */
#endif
} evInfo = {
{ 0, 0, 0 },
#endif
};
-/* Initialize a struct GenHeader */
+/** Initialize a struct GenHeader.
+ * @param[in,out] gen GenHeader to initialize.
+ * @param[in] call Callback for generated events.
+ * @param[in] data User data pointer.
+ * @param[in] next Pointer to next generator.
+ * @param[in,out] prev_p Pointer to previous pointer for this list.
+ */
static void
gen_init(struct GenHeader* gen, EventCallBack call, void* data,
struct GenHeader* next, struct GenHeader** prev_p)
}
}
-/* Execute an event; optimizations should inline this */
+/** Execute an event.
+ * Optimizations should inline this.
+ * @param[in] event Event to execute.
+ */
static void
event_execute(struct Event* event)
{
}
#ifndef IRCD_THREADED
-/* we synchronously execute the event when not threaded */
+/** we synchronously execute the event when not threaded */
#define event_add(event) \
do { \
struct Event* _ev = (event); \
} while (0)
#else
-/* add an event to the work queue */
+/** Add an event to the work queue.
+ * @param[in] event Event to enqueue.
+ */
/* This is just a placeholder; don't expect ircd to be threaded soon */
/* There should be locks all over the place in here */
static void
}
#endif /* IRCD_THREADED */
-/* Place a timer in the correct spot on the queue */
+/** Place a timer in the correct spot on the queue.
+ * @param[in] timer Timer to enqueue.
+ */
static void
timer_enqueue(struct Timer* timer)
{
*ptr_p = timer;
}
-/* signal handler for writing signal notification to pipe */
+/** &Signal handler for writing signal notification to pipe.
+ * @param[in] sig Signal number that just happened.
+ */
static void
signal_handler(int sig)
{
write(sigInfo.fd, &c, 1);
}
-/* callback for signal "socket" events */
+/** Callback for signal "socket" (really pipe) events.
+ * @param[in] event Event activity descriptor.
+ */
static void
signal_callback(struct Event* event)
{
}
}
-/* Remove something from its queue */
+/** Remove a generator from its queue.
+ * @param[in] arg Pointer to a GenHeader to dequeue.
+ */
void
gen_dequeue(void* arg)
{
gen->gh_prev_p = 0;
}
-/* Initializes the event system */
+/** Initializes the event system.
+ * @param[in] max_sockets Maximum number of sockets to support.
+ */
void
event_init(int max_sockets)
{
}
}
-/* Do the event loop */
+/** Do the event loop. */
void
event_loop(void)
{
(*evInfo.engine->eng_loop)(&evInfo.gens);
}
-/* Generate an event and add it to the queue (or execute it) */
+/** Generate an event and add it to the queue (or execute it).
+ * @param[in] type Type of event to generate.
+ * @param[in] arg Pointer to an event generator (GenHeader).
+ * @param[in] data Extra data for event.
+ */
void
event_generate(enum EventType type, void* arg, int data)
{
}
#endif
-/* Initialize a timer structure */
+/** Initialize a timer structure.
+ * @param[in,out] timer Timer to initialize.
+ * @return The pointer \a timer.
+ */
struct Timer*
timer_init(struct Timer* timer)
{
return timer; /* convenience return */
}
-/* Add a timer to be processed */
+/** Add a timer to be processed.
+ * @param[in] timer Timer to add.
+ * @param[in] call Callback for when the timer expires or is removed.
+ * @param[in] data User data pointer for the timer.
+ * @param[in] type Timer type.
+ * @param[in] value Timer expiration, duration or interval (per \a type).
+ */
void
timer_add(struct Timer* timer, EventCallBack call, void* data,
enum TimerType type, time_t value)
timer_enqueue(timer); /* and enqueue it */
}
-/* Remove a timer from the processing queue */
+/** Remove a timer from the processing queue.
+ * @param[in] timer Timer to remove.
+ */
void
timer_del(struct Timer* timer)
{
event_generate(ET_DESTROY, timer, 0);
}
-/* Change the time a timer expires */
+/** Change the time a timer expires.
+ * @param[in] timer Timer to update.
+ * @param[in] type New timer type.
+ * @param[in] value New timer expiration value.
+ */
void
timer_chg(struct Timer* timer, enum TimerType type, time_t value)
{
timer_enqueue(timer); /* re-queue the timer */
}
-/* Execute all expired timers */
+/** Execute all expired timers. */
void
timer_run(void)
{
}
}
-/* Adds a signal to the event callback system */
+/** Adds a signal to the event callback system.
+ * @param[in] signal Signal event generator to use.
+ * @param[in] call Callback function to use.
+ * @param[in] data User data pointer for generator.
+ * @param[in] sig Signal number to hook.
+ */
void
signal_add(struct Signal* signal, EventCallBack call, void* data, int sig)
{
}
}
-/* Adds a socket to the event system */
+/** Adds a socket to the event system.
+ * @param[in] sock Socket event generator to use.
+ * @param[in] call Callback function to use.
+ * @param[in] data User data pointer for the generator.
+ * @param[in] state Current socket state.
+ * @param[in] events Event interest mask for connected or connectionless sockets.
+ * @param[in] fd &Socket file descriptor.
+ * @return Zero on error, non-zero on success.
+ */
int
socket_add(struct Socket* sock, EventCallBack call, void* data,
enum SocketState state, unsigned int events, int fd)
return (*evInfo.engine->eng_add)(sock); /* tell engine about it */
}
-/* deletes (or marks for deletion) a socket */
+/** Deletes (or marks for deletion) a socket generator.
+ * @param[in] sock Event generator to clear.
+ */
void
socket_del(struct Socket* sock)
{
}
}
-/* Sets the socket state to something else */
+/** Sets the socket state to something else.
+ * @param[in] sock Socket generator to update.
+ * @param[in] state New socket state.
+ */
void
socket_state(struct Socket* sock, enum SocketState state)
{
sock->s_state = state; /* set new state */
}
-/* sets the events a socket's interested in */
+/** Sets the events a socket's interested in.
+ * @param[in] sock Socket generator to update.
+ * @param[in] events New event interest mask.
+ */
void
socket_events(struct Socket* sock, unsigned int events)
{
sock->s_events = new_events; /* set new events */
}
-/* Returns an engine's name for informational purposes */
+/** Returns the current engine's name for informational purposes.
+ * @return Pointer to a static buffer containing the engine name.
+ */
const char*
engine_name(void)
{
#ifdef DEBUGMODE
/* These routines pretty-print names for states and types for debug printing */
+/** Declares a struct variable containing name(s) and value(s) of \a TYPE. */
#define NS(TYPE) \
struct { \
char *name; \
TYPE value; \
}
+/** Declares an element initialize for an NS() struct. */
#define NM(name) { #name, name }
+/** Declares end of an NS() struct array. */
#define NE { 0 }
+/** Looks up name for a socket state.
+ * @param[in] state &Socket state to look up.
+ * @return Pointer to a static buffer containing the name, or "Undefined socket state".
+ */
const char*
state_to_name(enum SocketState state)
{
return "Undefined socket state";
}
+/** Looks up name for a timer type.
+ * @param[in] type &Timer type to look up.
+ * @return Pointer to a static buffer containing the name, or "Undefined timer type".
+ */
const char*
timer_to_name(enum TimerType type)
{
return "Undefined timer type";
}
+/** Looks up name for an event type.
+ * @param[in] type &Event type to look up.
+ * @return Pointer to a static buffer containing the name, or "Undefined event type".
+ */
const char*
event_to_name(enum EventType type)
{
return "Undefined event type";
}
+/** Constructs a string describing certain generator flags.
+ * @param[in] flags Bitwise combination of generator flags.
+ * @return Pointer to a static buffer containing the names of flags set in \a flags.
+ */
const char*
gen_flags(unsigned int flags)
{
return buf;
}
+/** Constructs a string describing certain socket flags.
+ * @param[in] flags Bitwise combination of socket flags.
+ * @return Pointer to a static buffer containing the names of flags set in \a flags.
+ */
const char*
sock_flags(unsigned int flags)
{