Socket_poll documentation -- functions

Initialization function

Function: socket_poll_init()
Returns: TRUE on success and FALSE on failure
Type: int
Parameter[1]: Value for the _MAP_COMPRESSED_GROW number
Type[1]: size_t
Parameter[2]: Value for _MAP_TYPE
Type[2]: int
Explanation:

This function needs to be called before any of the other functions are called.

Note:

If you pass 0 as the _MAP_COMPRESSED_GROW argument a default value will be given.

If you pass 0 as the _MAP_TYPE argument a default value will be given.

This function should only be called once.

Functions to add/remove from the socket poll

Function: socket_poll_add();
Returns: a socket poll offset number
Type: unsigned int
Parameter[1]: fd
Type[1]: int
Explanation:

This function will add an offset from the current group of offsets.

Note:

When using _MAP_DIRECT the returned offset may already be used by someone else.

Function: void socket_poll_del();
Returns: nothing
Type: void
Parameter[1]: Offset value return'd from socket_poll_add()
Type[1]: unsigned int
Explanation:

This function will remove an offset from the current group of offsets.

Note:

When using _MAP_DIRECT the passed offset may still be being used by someone else.

Updateing the socket poll

Function: socket_poll_update_all();
Returns: Number of offset's with state, or -1 and sets errno
Type: int
Parameter[1]: milliseconds of time to wait
Type[1]: int
Explanation:

This function will update all of the offset's (struct pollfd *), chaging the revents member. It will return either when something interesting has happened, or after the timeout has expired.

Note:

This function _doesn't_ return the number of interesting fds, it returns the number of intersting offsets. This is the same if you are using _MAP_DIRECT but is very different if you are using _MAP_COMPRESSED.

Function: socket_poll_update_overload();
Returns: Number of passed pollfd's with state, or -1 and sets errno
Type: int
Parameter[1]: Array of pollfd structures
Type[1]: struct pollfd *
Parameter[3]: Number of pollfds given in Parameter[1]
Type[3]: int
Parameter[3]: Milliseconds of time to wait
Type[3]: int
Explanation:

This function will update all of the offset's (struct pollfd *), and the array in Paramater[1]. It will return either when something interesting has happened, or after the timeout has expired.

Note:

This function works as if the socket poll offsets didn't exist. You need to have used SOCKET_POLL_OPT_SET_OVERLOAD_FUNC or nothing will be notified when their is state on the offset array.

Everything said for _update_all() applies to this function as well.

Function: int socket_poll_update_one();
Returns: 0 or 1 depending on if offset has state, or -1 and sets errno
Type: int
Parameter[1]: socket poll offset
Type[1]: unsigned int
Parameter[2]: milliseconds of time to wait
Type[2]: int
Explanation:

This function will update the offset's (struct pollfd *), chaging the revents member. It will return either when something interesting has happened, or after the timeout has expired.

Functions for miscellaneous control of options

Function: socket_poll_cntl_opt()
Returns:
Type: int
Parameter[1]:
Type[1]: int
Parameter[ ... ]: options depending on value of Parameter[1]
Type[ ... ]: Default stdarg/vararg promotion
Explanation:

See the SOCKET_POLL_CNTL_OPT_ macros for options.

Note:

This function isn't needed for simple uses of socket_poll.

Macro functions to use a socket poll offset

Function: SOCKET_POLL_INDICATOR()
Returns: poll structure
Type: struct pollfd *
Parameter[1]: socket poll offset
Type[1]: unsigned int
Explanation:

This function is used to access the struct pollfd structure accociated with a socket poll offset.

Note:

You are allowed to, and indeed should, alter the (struct pollfd *)->events member. However you should be careful about altering ->revents when using _MAP_DIRECT mapping because it will be altered for all the other users of the offset.