System

The System API is used to operate the moep system. More...

Files
file	system.h

Typedefs
typedef struct moep_callback *	moep_callback_t
	a moep callback More...
typedef int(*	cb_handler )(int, u32, void *)
	a callback handler More...
typedef int(*	sig_handler )(struct signalfd_siginfo *siginfo, void *)
	a signal handler More...

Functions
moep_callback_t	moep_callback_create (int fd, cb_handler handler, void *data, u32 events)
	create a new moep callback More...
int	moep_callback_change (moep_callback_t callback, u32 events)
	change a moep callback More...
int	moep_callback_delete (moep_callback_t callback)
	delete a moep callback More...
void	moep_set_custom_wait (int(*wait)(int, struct epoll_event *, int, int, const sigset_t *))
	set a custom wait call More...
int	moep_wait (int epfd, struct epoll_event *events, int maxevents, int timeout, const sigset_t *sigmask)
	wait for an I/O event on an epoll file descriptor More...
int	moep_run (sig_handler sigh, void *data)
	run the moep multiplexer More...

Detailed Description

The System API is used to operate the moep system.

Typedef Documentation

typedef struct moep_callback* moep_callback_t

a moep callback

This is the opaque representation of a callback.

typedef int(* cb_handler)(int, u32, void *)

a callback handler

A cb_handler() is a function pointer that is called by moep_wait() if the corresponding I/O event occurred.

Parameters

fd	the file descriptor on which the event occurred
events	the event(s)
data	user specified data

Returns

The cb_handler() must either return 0, or moep_wait() returns with this return value.

typedef int(* sig_handler)(struct signalfd_siginfo *siginfo, void *)

a signal handler

A sig_handler() is a function pointer that is called by moep_run() if a signal occurs. The signals are internally delivered via a signalfd. See the respective manual page for details. Information on the contents of siginfo can also be found in the manual page of signalfd. As the sig_handler() is not called asynchronously, the actions of the handler are not limited to signal-safe functions.

Parameters

siginfo	information on the signal
data	user specified data

Returns

The signal handler must either return 0, or moep_run() returns with this return value.

Function Documentation

moep_callback_t moep_callback_create	(	int	fd,
		cb_handler	handler,
		void *	data,
		u32	events
	)

create a new moep callback

The moep_callback_create() call is used to create a new moep callback. Whenever the I/O events specified in events occur on the file descriptor fd the callback function handler is called with data as argument. The events are the same as for epoll_ctl(). See the respective manual page for details. To make the callback happen a call to moep_wait() or better moep_run() is necessary.

Parameters

fd	the file descriptor to be watched
handler	the callback handler
the	argument for handler
events	the events to wait for

int moep_callback_change	(	moep_callback_t	callback,
		u32	events
	)

change a moep callback

The moep_callback_change() call is used to cahnge the events the callback should wait for. The events are the same as for epoll_ctl(). See the respective manual page for details.

Parameters

callback	the moep callback
events	the events to wait for

int moep_callback_delete

(

moep_callback_t

callback

)

delete a moep callback

The moep_callback_delete() call is used to delete a moep callback.

Parameters

callback

the moep callback

void moep_set_custom_wait

(

int(*)(int, struct epoll_event *, int, int, const sigset_t *)

wait

)

set a custom wait call

The moep_set_custom_wait() call is used to customize the moep_wait() call. Normally, moep_wait() uses epoll_pwait() internally. With this call you can specify a custom wait call wich should be used instead.

Warning

You need very good reasons to call moep_set_custom_wait(). This call is only usefull if you want to integrate another existing run loop implementation that works similiar to moep_wait().

Parameters

wait	the custom wait call

int moep_wait	(	int	epfd,
		struct epoll_event *	events,
		int	maxevents,
		int	timeout,
		const sigset_t *	sigmask
	)

wait for an I/O event on an epoll file descriptor

The moep_wait() call waits for events on the epoll instance referred to by the file descriptor epfd. The call works similiar to epoll_pwait() and the parameters are identical. See the respective manual page for more details. Differences to epoll_pwait() are noted below.

During waiting for the specified I/O events moep_wait() also waits for the events specified by callbacks registered with moep_callback_create(). If such events occur the respective callback functions are called. Depending on the return value of such a callback moep_wait() either returns this return value or keeps waiting if the return value was 0.

Warning

You need very good reasons to call moep_wait() directly. Normally, using moep_run() is the intended usage. Its sole purpose is the ability to stack another custom wait call on it. This stacking can also be done in the other direction via moep_set_custom_wait().

Returns

The return values are the same as for epoll_pwait. Additionally, arbitrary values can be returned by a callback.

Errors

The error values are the same as for epoll_pwait(). Additionally, arbitrary error values can be returned by a callback.

int moep_run	(	sig_handler	sigh,
		void *	data
	)

run the moep multiplexer

The moep_run() call is the main run loop of libmoep. While executing the event loop, callbacks registered with moep_callback_create() will be called for the specified I/O events. If the return value of such a callback is nonzero, moep_run() returns with that return value. There is one exception to that rule, namely if errno is EINTR, moep_run() keeps running.

The moep_run() call blocks all currently unblocked signals and uses a signalfd to read those signals in a sychronous way. For each delivered signal sigh is called with data as argument. The return value of sigh determines if moep_run() returns, i.e., if the return value is 0 moep_run() keeps running, otherwise moep_run() returns the return value. If sigh is NULL, signals are ignored.

Parameters

sigh	the signal handler
data	the argument for sigh

Returns

This call does not return until an error occured or a callback returned with a nonzero value.

Return values

-1	on error, errno is set appropriately.

Errors

The error values are the same as for moep_wait(), except that EINTR is handled internally. Additionally, arbitrary error values can be returned by a callback.