An OS independent wrapper for polling I/O connections. More...

#include "<SaS/Common/Poll.hpp>"

Inheritance diagram for SoftwareAndServices::Library::Common::Poll:

Collaboration diagram for SoftwareAndServices::Library::Common::Poll:

Classes
struct	CallBacks

Public Member Functions
	Poll ()
	Poll - default Constructor. More...

virtual	~Poll ()
	Poll Destructor. More...

bool	AddFd (const int fd, const unsigned short events, const CallBacks *cb=nullptr)
	Add fd the the list of callback that the current callback function will handle when cb is nullptr. More...

void	CloseDown ()
	Close down everything. More...

virtual InstanceCount_t	decInstance () const
	Decrement the instance. More...

void	Disable (const int fd, const unsigned short events)
	Disable All Transport & User callbacks for fd for events. More...

void	Enable (const int fd, const unsigned short events)
	Enable All T& User callbacks for fd for events. More...

File *	GetFile (const int fd)
	Get a File handle to the named file descriptor. More...

virtual InstanceCount_t	getInstance () const

PollFunc_t	GetTransportAcceptCallback () const

PollFunc_t	GetTransportCallback (const int fd, const unsigned short events) const
	Get any Transport callback function for fd using events. More...

CallBacks *	GetTransportCallbacks () const
	Get the Transport callbacks. More...

void *	GetTransportData () const

PollFunc_t	GetTransportDefaultCallback (const unsigned short events) const
	Get the Transport default callback function for the named events. More...

PollFunc_t	GetUserAcceptCallback () const

PollFunc_t	GetUserCallback (const int Fd, unsigned short Events) const
	Get any User callback function for fd using events. More...

CallBacks *	GetUserCallbacks () const
	Get the User callbacks. More...

void *	GetUserData () const

PollFunc_t	GetUserDefaultCallback (const unsigned short events) const
	Get the User default callback function for the named events. More...

virtual InstanceCount_t	incInstance () const
	Increment the instance. More...

void	Lock ()
	Lock this data so changes can be made. More...

void	operator delete (void *ToFree)

const struct pollfd *	PollFd () const

nfds_t	PollFdSize () const

bool	RemoveFd (const int fd)
	Remove fd from the poll list. More...

void	SetTimeout (const int milliseconds)

void	SetTransportAcceptCallback (const PollFunc_t ThePollFunc, const void *userData=nullptr)
	Set Transport accept call back. More...

void	SetTransportCallback (const int fd, const unsigned short events, const PollFunc_t ThePollFunc, const unsigned int bufSize)
	Set the a Transport callback. More...

void	SetTransportData (const void *Data)

void	SetTransportDefaultCallback (const unsigned short events, const PollFunc_t ThePollFunc, const unsigned int bufSize)
	Set the default Transport callback. More...

void	SetTransportFillRdCallback (const int fd, const unsigned short events, const PollFunc_t ThePollFunc, const unsigned int bufsize)
	Set the Transport callback. More...

void	SetUserAcceptCallback (const PollFunc_t ThePollFunc, const void *userData=nullptr)
	Set User accept call back. More...

void	SetUserCallback (const int fd, const unsigned short events, const PollFunc_t ThePollFunc, const unsigned int bufSize)
	Set the a User callback. More...

void	SetUserData (const void *Data)

void	SetUserData (int fd, const void *Data)

void	SetUserDefaultCallback (const unsigned short events, const PollFunc_t ThePollFunc, const unsigned int bufSize=0)
	Set the default User callback. More...

void	SetUserFillRdCallback (const int fd, const unsigned short events, const PollFunc_t ThePollFunc, const unsigned int bufsize)
	USER (only used for callbacks, and sets Transport FD poll fd's). More...

void	TransportDisable (const int fd, const unsigned short events)
	Disable Transport callbacks for fd for events. More...

void	TransportEnable (const int fd, const unsigned short events)
	Enable Transport callbacks for fd for events. More...

void	Unlock ()
	Unlock this data, changes are complete. More...

void	UserDisable (const int fd, const unsigned short events)
	Disable User callbacks for fd for events. More...

void	UserEnable (const int fd, const unsigned short events)
	Enable User callbacks for fd for events. More...

int	Wait (bool Once=false)
	Only call after struct pollfd (below) is setup. More...

int	WakeUpFd () const
	Get the wake up FD. More...

Static Public Member Functions
static void *	GetUserData (int fd)

Public Attributes
EXPORT_COMMON typedef int(*	PollFunc_t )(const int fd, const unsigned short revents, CallBacks callBacks, const unsigned int len, const char data)
	For FILL-READ callback len and data are supplied, else they are zero and nullptr. More...

Friends
void *	_WakeUpThread (void *)

void	AtExitCleanup ()
	One time global initialization. More...

Detailed Description

An OS independent wrapper for polling I/O connections.

Poll Events:

POLLIN Data other than high priority data may be read without blocking. For STREAMS, this flag is set in revents even if the message is of zero length.
POLLRDBAND Data from a non-zero priority band may be read without blocking. For STREAMS, this flag is set in revents even if the message is of zero length.
POLLPRI High priority data may be received without blocking. For STREAMS, this flag is set in revents even if the message is of zero length.
POLLOUT Normal data (priority band equals 0) may be written without blocking.

Warning: POLLOUT will generate a massive amount of callback calls as most devices are almost always ready to be written to. Suggest only using this for extremely slow devices where you really need to know if it can be written to.

POLLWRBAND Priority data (priority band > 0) may be written. This event only examines bands that have been written to at least once.
POLLERR An error has occurred on the device or stream. This flag is only valid in the revents bitmask; it is not used in the events member.
POLLHUP A hang-up has occurred on the stream. This event and POLLOUT are mutually exclusive; a stream can never be writable if a hang-up has occurred. However, this event and POLLIN, POLLRDBAND, or POLLPRI are not mutually exclusive. This flag is only valid in the revents bitmask; it is not used in the events member.
POLLNVAL The specified fd value does not belong to an open file. This flag is only valid in the revents member; it is not used in the events member.

This implementation has two level, the OS level (T meaning transport) and the user level (User).

The User level is what the calling program uses to set or get data or callbacks.

The Transport level is the implementation specific level. Normally calling program never use the Transport level.

This implementation uses the POSIX poll() on systems that have it, or a private implementation that uses select() on systems that have that.

In addition to emulating the features of POSIX poll() this implementation will buffer in or out the data. The caller can for example pass a buffer down and have this implementation send it (or fill it) to/from the designated FD asynchronously of the calling program. Then callback the calling programs handler to notify it that the task is complete.

Definition at line 237 of file Poll.hpp.

Constructor & Destructor Documentation

◆ Poll()

SoftwareAndServices::Library::Common::Poll::Poll ( )

Poll - default Constructor.

◆ ~Poll()

virtual SoftwareAndServices::Library::Common::Poll::~Poll ( )

virtual

Poll Destructor.

Member Function Documentation

◆ AddFd()

bool SoftwareAndServices::Library::Common::Poll::AddFd	(	const int	fd,
		const unsigned short	events,
		const CallBacks *	cb = `nullptr`
	)

Add fd the the list of callback that the current callback function will handle when cb is nullptr.

If cb is non-nullptr, then add cb as a handler for fd and events.

Parameters

fd	The file descriptor to add.
events	the events to handle.
cb	An optional callback to add.

◆ CloseDown()

void SoftwareAndServices::Library::Common::Poll::CloseDown ( )

Close down everything.

This closes down all the sockets, and closes all the file descriptors.

◆ decInstance()

virtual InstanceCount_t SoftwareAndServices::Library::Common::instance< Poll >::decInstance ( ) const

inlinevirtualinherited

Decrement the instance.

Returns: The instance count, after decrementing it.

Definition at line 129 of file instance.hpp.

◆ Disable()

void SoftwareAndServices::Library::Common::Poll::Disable	(	const int	fd,
		const unsigned short	events
	)

Disable All Transport & User callbacks for fd for events.

Parameters

fd	The fd to disable.
events	The events to disable for fd.

◆ Enable()

void SoftwareAndServices::Library::Common::Poll::Enable	(	const int	fd,
		const unsigned short	events
	)

Enable All T& User callbacks for fd for events.

Parameters

fd	The fd to disable.
events	The events to disable for fd.

◆ GetFile()

File* SoftwareAndServices::Library::Common::Poll::GetFile ( const int fd )

Get a File handle to the named file descriptor.

fd can be a file or a socket.

Parameters

fd	A file handle or descriptor.

Returns: A File object or nullptr if not allowed because of fd type.

◆ getInstance()

virtual InstanceCount_t SoftwareAndServices::Library::Common::instance< Poll >::getInstance ( ) const

inlinevirtualinherited

Returns: The current instance count.

Definition at line 118 of file instance.hpp.

◆ GetTransportAcceptCallback()

PollFunc_t SoftwareAndServices::Library::Common::Poll::GetTransportAcceptCallback ( ) const

Returns: The Transport ACCEPT callback function.

◆ GetTransportCallback()

PollFunc_t SoftwareAndServices::Library::Common::Poll::GetTransportCallback	(	const int	fd,
		const unsigned short	events
	)		const

Get any Transport callback function for fd using events.

Returns: The PollFunc_t for the named fd and events. Returns nullptr if none, or no single PollFunc_t is used for all events.

◆ GetTransportCallbacks()

CallBacks* SoftwareAndServices::Library::Common::Poll::GetTransportCallbacks ( ) const

Get the Transport callbacks.

Returns: The Transport callbacks.

◆ GetTransportData()

void* SoftwareAndServices::Library::Common::Poll::GetTransportData ( ) const

Returns: The default server data (Transport).

◆ GetTransportDefaultCallback()

PollFunc_t SoftwareAndServices::Library::Common::Poll::GetTransportDefaultCallback ( const unsigned short events ) const

Get the Transport default callback function for the named events.

If events are handled by more than one callback, then this function will return nullptr. The best way to call it, where there is a possibility of multiple callbacks, each for a unique set of events, is to make this call with one poll event at a time.

Parameters

events Which events to look for.

Returns: The PollFunc_t callback. Or null if none.

◆ GetUserAcceptCallback()

PollFunc_t SoftwareAndServices::Library::Common::Poll::GetUserAcceptCallback ( ) const

Returns: The User ACCEPT callback function.

◆ GetUserCallback()

PollFunc_t SoftwareAndServices::Library::Common::Poll::GetUserCallback	(	const int	Fd,
		unsigned short	Events
	)		const

Get any User callback function for fd using events.

Parameters

Fd	The file descriptor to search for.
Events	The callback method that handles the bits in Events.

Returns: The PollFunc_t for the named Fd and Events. Returns nullptr if none, or no single PollFunc_t is used for all events.

◆ GetUserCallbacks()

CallBacks* SoftwareAndServices::Library::Common::Poll::GetUserCallbacks ( ) const

Get the User callbacks.

Returns: The User callbacks.

◆ GetUserData() [1/2]

void* SoftwareAndServices::Library::Common::Poll::GetUserData ( ) const

Returns: The default server data (User).

◆ GetUserData() [2/2]

static void* SoftwareAndServices::Library::Common::Poll::GetUserData ( int fd )

static

Parameters

fd	The file descriptors data to fetch.

Returns: The server data (User) for the provided file descriptor.

◆ GetUserDefaultCallback()

PollFunc_t SoftwareAndServices::Library::Common::Poll::GetUserDefaultCallback ( const unsigned short events ) const

Get the User default callback function for the named events.

If events are handled by more than one callback, then this function will return nullptr. The best way to call it, where there is a possibility of multiple callbacks, each for a unique set of events, is to make this call with one poll event at a time.

Parameters

events Which events to look for.

Returns: The PollFunc_t callback. Or null if none.

◆ incInstance()

virtual InstanceCount_t SoftwareAndServices::Library::Common::instance< Poll >::incInstance ( ) const

inlinevirtualinherited

Increment the instance.

Returns: The instance value, after incrementing it.

Definition at line 109 of file instance.hpp.

◆ Lock()

void SoftwareAndServices::Library::Common::Poll::Lock ( )

inline

Lock this data so changes can be made.

See also: Unlock()

Definition at line 634 of file Poll.hpp.

◆ PollFd()

const struct pollfd* SoftwareAndServices::Library::Common::Poll::PollFd ( ) const

Returns: The polling structure being used.

◆ PollFdSize()

nfds_t SoftwareAndServices::Library::Common::Poll::PollFdSize ( ) const

Returns: the number of objects being polled.

◆ RemoveFd()

bool SoftwareAndServices::Library::Common::Poll::RemoveFd ( const int fd )

Remove fd from the poll list.

Parameters

fd	The file descriptor to stop polling.

Returns: TRUE if removed.

◆ SetTimeout()

void SoftwareAndServices::Library::Common::Poll::SetTimeout ( const int milliseconds )

Parameters

milliseconds How long for poll() to wait.

◆ SetTransportAcceptCallback()

void SoftwareAndServices::Library::Common::Poll::SetTransportAcceptCallback	(	const PollFunc_t	ThePollFunc,
		const void *	userData = `nullptr`
	)

Set Transport accept call back.

Parameters

ThePollFunc	The name of the callback that handles notifications that an ACCEPT is available. (server accepting new incoming connections)
userData	Optional user data to be remembered and passed back to ThePollFunc when called.

◆ SetTransportCallback()

void SoftwareAndServices::Library::Common::Poll::SetTransportCallback	(	const int	fd,
		const unsigned short	events,
		const PollFunc_t	ThePollFunc,
		const unsigned int	bufSize
	)

Set the a Transport callback.

Set to nullptr and it will disable it. Setting it to non-nullptr will NOT enable it - use Enable(). Used to override the default Transport callback for the named events.

Parameters

fd	Use the ThePollFunc for event with this fd
events	The poll events that ThePollFunc will handle.
ThePollFunc	A callback to be called for the named events.
bufSize	...

◆ SetTransportData()

void SoftwareAndServices::Library::Common::Poll::SetTransportData ( const void * Data )

Parameters

Data	- Default server data (Transport) to use.

◆ SetTransportDefaultCallback()

void SoftwareAndServices::Library::Common::Poll::SetTransportDefaultCallback	(	const unsigned short	events,
		const PollFunc_t	ThePollFunc,
		const unsigned int	bufSize
	)

Set the default Transport callback.

Set to nullptr and it will disable it. Setting it to non-nullptr will NOT enable it - use Enable().

Parameters

events	The poll events that ThePollFunc will handle.
ThePollFunc	A callback to be called for the named events.
bufSize	Size of the buffer desired.

◆ SetTransportFillRdCallback()

void SoftwareAndServices::Library::Common::Poll::SetTransportFillRdCallback	(	const int	fd,
		const unsigned short	events,
		const PollFunc_t	ThePollFunc,
		const unsigned int	bufsize
	)

Set the Transport callback.

Does an IOCTL to the FD, determines the number of bytes that can be read, and fills the buffer to the amount readable.

Parameters

fd	The file descriptor to work with.
bufsize	is the MAX memory buffer allowed. After that, it is MMAP'd and the calling function MUST un-map it when done.
events	Which poll events to use.
ThePollFunc	The callback function to call.

◆ SetUserAcceptCallback()

void SoftwareAndServices::Library::Common::Poll::SetUserAcceptCallback	(	const PollFunc_t	ThePollFunc,
		const void *	userData = `nullptr`
	)

Set User accept call back.

Parameters

ThePollFunc	The name of the callback that handles notifications that an ACCEPT is available. (server accepting new incoming connections)
userData	Optional user data to be remembered and passed back to ThePollFunc when called.

◆ SetUserCallback()

void SoftwareAndServices::Library::Common::Poll::SetUserCallback	(	const int	fd,
		const unsigned short	events,
		const PollFunc_t	ThePollFunc,
		const unsigned int	bufSize
	)

Set the a User callback.

Set to nullptr and it will disable it. Setting it to non-nullptr will NOT enable it - use Enable(). Used to override the default User callback for the named events.

Parameters

fd	Use the ThePollFunc for event with this fd
events	The poll events that ThePollFunc will handle.
ThePollFunc	A callback to be called for the named events.
bufSize	...

◆ SetUserData() [1/2]

void SoftwareAndServices::Library::Common::Poll::SetUserData ( const void * Data )

Parameters

Data	Default server data (User) to use.

◆ SetUserData() [2/2]

void SoftwareAndServices::Library::Common::Poll::SetUserData	(	int	fd,
		const void *	Data
	)

Parameters

Data	Default server data (User) to use for the provided file descriptor.
fd	The file descriptor that matches this Data.

◆ SetUserDefaultCallback()

void SoftwareAndServices::Library::Common::Poll::SetUserDefaultCallback	(	const unsigned short	events,
		const PollFunc_t	ThePollFunc,
		const unsigned int	bufSize = `0`
	)

Set the default User callback.

Set to nullptr and it will disable it. Setting it to non-nullptr will NOT enable it - use Enable().

Parameters

events	The poll events that ThePollFunc will handle.
ThePollFunc	A callback to be called for the named events.
bufSize	Size of the buffer desired.

◆ SetUserFillRdCallback()

void SoftwareAndServices::Library::Common::Poll::SetUserFillRdCallback	(	const int	fd,
		const unsigned short	events,
		const PollFunc_t	ThePollFunc,
		const unsigned int	bufsize
	)

USER (only used for callbacks, and sets Transport FD poll fd's).

Set the User callback. Does an IOCTL to the FD, determines the number of bytes that can be read, and fills the buffer to the amount readable.

Parameters

fd	The file descriptor to work with.
events	Which poll events to use.
ThePollFunc	The callback function to call.
bufsize	is the MAX memory buffer allowed. After that, it is MMAP'd and the calling function MUST un-map it when done.

◆ TransportDisable()

void SoftwareAndServices::Library::Common::Poll::TransportDisable	(	const int	fd,
		const unsigned short	events
	)

Disable Transport callbacks for fd for events.

Parameters

fd	The fd to disable.
events	The events to disable for fd.

◆ TransportEnable()

void SoftwareAndServices::Library::Common::Poll::TransportEnable	(	const int	fd,
		const unsigned short	events
	)

Enable Transport callbacks for fd for events.

Parameters

fd	The fd to disable.
events	The events to disable for fd.

◆ Unlock()

void SoftwareAndServices::Library::Common::Poll::Unlock ( )

inline

Unlock this data, changes are complete.

See also: Lock()

Definition at line 644 of file Poll.hpp.

◆ UserDisable()

void SoftwareAndServices::Library::Common::Poll::UserDisable	(	const int	fd,
		const unsigned short	events
	)

Disable User callbacks for fd for events.

Parameters

fd	The fd to disable.
events	The events to disable for fd.

◆ UserEnable()

void SoftwareAndServices::Library::Common::Poll::UserEnable	(	const int	fd,
		const unsigned short	events
	)

Enable User callbacks for fd for events.

Parameters

fd	The fd to disable.
events	The events to disable for fd.

◆ Wait()

int SoftwareAndServices::Library::Common::Poll::Wait ( bool Once = false )

Only call after struct pollfd (below) is setup.

Parameters

Once	When true, only check once, then exit.

Returns: The number of un-processed poll() fd's.

◆ WakeUpFd()

int SoftwareAndServices::Library::Common::Poll::WakeUpFd ( ) const

Get the wake up FD.

Send a 'Q' to this fd to have poll(2) quit.

Send a 'W' to wake up poll(2) when you add/delete/update file descriptors to the poll(2) list.

Anything else sent will be treated as a 'W' - not recommended as applications may have other meaning for the value.

Returns: the wake up file descriptor.

Warning: Do no close this fd!

Friends And Related Function Documentation

◆ AtExitCleanup

void AtExitCleanup ( )

friend

One time global initialization.

Member Data Documentation

◆ PollFunc_t

EXPORT_COMMON typedef int(* SoftwareAndServices::Library::Common::Poll::PollFunc_t) (const int fd, const unsigned short revents, CallBacks *callBacks, const unsigned int len, const char *data)

For FILL-READ callback len and data are supplied, else they are zero and nullptr.

The is the function signature for a read callback. A read callback is called when the buffer is full of read information and is notifying the calling program that no more I/O will occur on this file handle until the buffer is emptied.

Parameters

fd	The file descriptor to work with.
revents	Which events logical OR of (POLL_ACCEPT_FD, POLLIN, POLLRDBAND, POLLPRI, POLLOUT, POLLWRBAND, POLLERR, POLLHUP, POLLNVAL)
callBacks	List of callbacks
len	How much to read (ignored with some callback options).
data	Where to put the data (ignored with some callback options)

Definition at line 268 of file Poll.hpp.

The documentation for this class was generated from the following file:

Poll.hpp

Classes

Public Member Functions

Static Public Member Functions

Public Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Poll()

◆ ~Poll()

Member Function Documentation

◆ AddFd()

◆ CloseDown()

◆ decInstance()

◆ Disable()

◆ Enable()

◆ GetFile()

◆ getInstance()

◆ GetTransportAcceptCallback()

◆ GetTransportCallback()

◆ GetTransportCallbacks()

◆ GetTransportData()

◆ GetTransportDefaultCallback()

◆ GetUserAcceptCallback()

◆ GetUserCallback()

◆ GetUserCallbacks()

◆ GetUserData() [1/2]

◆ GetUserData() [2/2]

◆ GetUserDefaultCallback()

◆ incInstance()

◆ Lock()

◆ PollFd()

◆ PollFdSize()

◆ RemoveFd()

◆ SetTimeout()

◆ SetTransportAcceptCallback()

◆ SetTransportCallback()

◆ SetTransportData()

◆ SetTransportDefaultCallback()

◆ SetTransportFillRdCallback()

◆ SetUserAcceptCallback()

◆ SetUserCallback()

◆ SetUserData() [1/2]

◆ SetUserData() [2/2]

◆ SetUserDefaultCallback()

◆ SetUserFillRdCallback()

◆ TransportDisable()

◆ TransportEnable()

◆ Unlock()

◆ UserDisable()

◆ UserEnable()

◆ Wait()

◆ WakeUpFd()

Friends And Related Function Documentation

◆ AtExitCleanup

Member Data Documentation

◆ PollFunc_t