Software and Services, Portable Libraries  2019.Mar.01
A library for managing digital certificates
SoftwareAndServices::Library::Common::Poll Class Reference

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...
 
FileGetFile (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...
 
CallBacksGetTransportCallbacks () 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...
 
CallBacksGetUserCallbacks () 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
fdThe file descriptor to add.
eventsthe events to handle.
cbAn 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
fdThe fd to disable.
eventsThe 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
fdThe fd to disable.
eventsThe 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
fdA 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
eventsWhich 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
FdThe file descriptor to search for.
EventsThe 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
fdThe 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
eventsWhich 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
fdThe file descriptor to stop polling.
Returns
TRUE if removed.

◆ SetTimeout()

void SoftwareAndServices::Library::Common::Poll::SetTimeout ( const int  milliseconds)
Parameters
millisecondsHow 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
ThePollFuncThe name of the callback that handles notifications that an ACCEPT is available. (server accepting new incoming connections)
userDataOptional 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
fdUse the ThePollFunc for event with this fd
eventsThe poll events that ThePollFunc will handle.
ThePollFuncA 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
eventsThe poll events that ThePollFunc will handle.
ThePollFuncA callback to be called for the named events.
bufSizeSize 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
fdThe file descriptor to work with.
bufsizeis the MAX memory buffer allowed. After that, it is MMAP'd and the calling function MUST un-map it when done.
eventsWhich poll events to use.
ThePollFuncThe 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
ThePollFuncThe name of the callback that handles notifications that an ACCEPT is available. (server accepting new incoming connections)
userDataOptional 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
fdUse the ThePollFunc for event with this fd
eventsThe poll events that ThePollFunc will handle.
ThePollFuncA callback to be called for the named events.
bufSize...

◆ SetUserData() [1/2]

void SoftwareAndServices::Library::Common::Poll::SetUserData ( const void *  Data)
Parameters
DataDefault server data (User) to use.

◆ SetUserData() [2/2]

void SoftwareAndServices::Library::Common::Poll::SetUserData ( int  fd,
const void *  Data 
)
Parameters
DataDefault server data (User) to use for the provided file descriptor.
fdThe 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
eventsThe poll events that ThePollFunc will handle.
ThePollFuncA callback to be called for the named events.
bufSizeSize 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
fdThe file descriptor to work with.
eventsWhich poll events to use.
ThePollFuncThe callback function to call.
bufsizeis 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
fdThe fd to disable.
eventsThe 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
fdThe fd to disable.
eventsThe 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
fdThe fd to disable.
eventsThe 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
fdThe fd to disable.
eventsThe events to disable for fd.

◆ Wait()

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

Only call after struct pollfd (below) is setup.

Parameters
OnceWhen 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
fdThe file descriptor to work with.
reventsWhich events logical OR of (POLL_ACCEPT_FD, POLLIN, POLLRDBAND, POLLPRI, POLLOUT, POLLWRBAND, POLLERR, POLLHUP, POLLNVAL)
callBacksList of callbacks
lenHow much to read (ignored with some callback options).
dataWhere 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: