File descriptors events multiplexing services.
[Xenomai nucleus.]

Collaboration diagram for File descriptors events multiplexing services.:

---

Detailed Description

File descriptors events multiplexing services.

This module implements the services needed for implementing the posix "select" service, or any other events multiplexing services.

Following the implementation of the posix select service, this module defines three types of events:

• XNSELECT_READ meaning that a file descriptor is ready for reading;
• XNSELECT_WRITE meaning that a file descriptor is ready for writing;
• XNSELECT_EXCEPT meaning that a file descriptor received an exceptional event.

It works by defining two structures:

• a struct xnselect structure, which should be added to every file descriptor for every event type (read, write, or except);
• a struct xnselector structure, the selection structure, passed by the thread calling the xnselect service, where this service does all its housekeeping.

Files
file	select.h
	file descriptors events multiplexing header.
file	select.c
	file descriptors events multiplexing.
Functions
void	xnselect_init (struct xnselect *select_block)
	Initialize a struct xnselect structure.
int	xnselect_bind (struct xnselect *select_block, struct xnselect_binding *binding, struct xnselector *selector, unsigned type, unsigned index, unsigned state)
	Bind a file descriptor (represented by its xnselect structure) to a selector block.
void	xnselect_destroy (struct xnselect *select_block)
	Destroy the xnselect structure associated with a file descriptor.
int	xnselector_init (struct xnselector *selector)
	Initialize a selector structure.
int	xnselect (struct xnselector *selector, fd_set *out_fds[XNSELECT_MAX_TYPES], fd_set *in_fds[XNSELECT_MAX_TYPES], int nfds, xnticks_t timeout, xntmode_t timeout_mode)
	Check the state of a number of file descriptors, wait for a state change if no descriptor is ready.
void	xnselector_destroy (struct xnselector *selector)
	Destroy a selector block.

---

Function Documentation

int xnselect	(	struct xnselector *	selector,
		fd_set *	out_fds[XNSELECT_MAX_TYPES],
		fd_set *	in_fds[XNSELECT_MAX_TYPES],
		int	nfds,
		xnticks_t	timeout,
		xntmode_t	timeout_mode
	)

Check the state of a number of file descriptors, wait for a state change if no descriptor is ready.

Parameters:

	selector	structure to check for pending events
	out_fds	The set of descriptors with pending events if a strictly positive number is returned, or the set of descriptors not yet bound if -ECHRNG is returned;
	in_fds	the set of descriptors which events should be checked
	nfds	the highest-numbered descriptor in any of the in_fds sets, plus 1;
	timeout	the timeout, whose meaning depends on timeout_mode, note that xnselect() pass timeout and timeout_mode unchanged to xnsynch_sleep_on, so passing a relative value different from XN_INFINITE as a timeout with timeout_mode set to XN_RELATIVE, will cause a longer sleep than expected if the sleep is interrupted.
	timeout_mode	the mode of timeout.

Return values:

	-EINVAL	if is negative;
	-ECHRNG	if some of the descriptors passed in in_fds have not yet been registered with xnselect_bind(), out_fds contains the set of such descriptors;
	-EINTR	if xnselect was interrupted while waiting;
	0	in case of timeout.
	the	number of file descriptors having received an event.

int xnselect_bind	(	struct xnselect *	select_block,
		struct xnselect_binding *	binding,
		struct xnselector *	selector,
		unsigned	type,
		unsigned	index,
		unsigned	state
	)

Bind a file descriptor (represented by its xnselect structure) to a selector block.

Parameters:

	select_block	pointer to the struct xnselect to be bound;
	binding	pointer to a newly allocated (using xnmalloc) struct xnselect_binding;
	selector	pointer to the selector structure;
	type	type of events (XNSELECT_READ, XNSELECT_WRITE, or XNSELECT_EXCEPT);
	index	index of the file descriptor (represented by select_block) in the bit fields used by the selector structure;
	state	current state of the file descriptor>.

select_block must have been initialized with xnselect_init(), the xnselector structure must have been initialized with xnselector_init(), binding may be uninitialized.

This service must be called with nklock locked, irqs off. For this reason, the binding parameter must have been allocated by the caller outside the locking section.

Return values:

	-EINVAL	if type or index is invalid;
	0	otherwise.

void xnselect_destroy

(

struct xnselect *

select_block

)

Destroy the xnselect structure associated with a file descriptor.

Any binding with a xnselector block is destroyed.

Parameters:

select_block

pointer to the xnselect structure associated with a file descriptor

void xnselect_init

(

struct xnselect *

select_block

)

Initialize a struct xnselect structure.

This service must be called to initialize a struct xnselect structure before it is bound to a selector by the means of xnselect_bind().

Parameters:

select_block

pointer to the xnselect structure to be initialized

void xnselector_destroy

(

struct xnselector *

selector

)

Destroy a selector block.

All bindings with file descriptor are destroyed.

Parameters:

selector

the selector block to be destroyed

int xnselector_init

(

struct xnselector *

selector

)

Initialize a selector structure.

Parameters:

selector

The selector structure to be initialized.

Return values:

0

---