le_fdMonitor.h File Reference

Prototype for file descriptor event handler functions.

Events that can be received:

• POLLIN = Data available to read.
• POLLPRI = Urgent data available to read (e.g., out-of-band data on a socket).
• POLLOUT = Writing to the fd should accept some data now.
• POLLRDHUP = Other end of stream socket closed or shutdown.
• POLLERR = Error occurred.
• POLLHUP = Hang up.

These are bitmask values that may appear in the events parameter. Use the bit-wise AND operator ('&') to test for specific events.

if (events & POLLIN)
{
    // Data available to read.
    ...
}
 
if (events & POLLERR)
{
    // An error occured.
    ...
}
 
...

Parameters

fd	[in] File descriptor.
events	[in] Bit map of events that occurred. Use bitwise AND ('&') to test for events.

File Descriptor Monitor reference.

Used to refer to File Descriptor Monitor objects.

Creates a File Descriptor Monitor.

Creates an object that will monitor a given file descriptor for events.

The monitoring will be performed by the event loop of the thread that created the Monitor object. If that thread is blocked, no events will be detected for that file descriptor until that thread is unblocked and returns to its event loop.

Events that can be enabled for monitoring:

• POLLIN = Data available to read.
• POLLPRI = Urgent data available to read (e.g., out-of-band data on a socket).
• POLLOUT = Writing to the fd should accept some data now.

These are bitmask values and can be combined using the bit-wise OR operator ('|').

The following events are always monitored, even if not requested:

• POLLRDHUP = Other end of stream socket closed or shutdown.
• POLLERR = Error occurred.

• POLLHUP = Hang up.

  Parameters

  [in]	name	Name of the object (for diagnostics).
  [in]	fd	File descriptor to be monitored for events.
  [in]	handlerFunc	Handler function.
  [in]	events	Initial set of events to be monitored.

  Returns

  Reference to the object, which is needed for later deletion.

  Note

  Doesn't return on failure, there's no need to check the return value for errors.

Deletes a file descriptor monitor object.

Parameters

[in]

monitorRef

Reference to the File Descriptor Monitor object.

Disables monitoring for events on a file descriptor.

Events that can be disabled for monitoring:

• POLLIN = Data available to read.
• POLLPRI = Urgent data available to read (e.g., out-of-band data on a socket).
• POLLOUT = Writing to the fd should accept some data now.

These are bitmask values and can be combined using the bit-wise OR operator ('|').

Parameters

[in]	monitorRef	Reference to the File Descriptor Monitor object.
[in]	events	Bit map of events.

Enables monitoring for events on a file descriptor.

Events that can be enabled for monitoring:

• POLLIN = Data available to read.
• POLLPRI = Urgent data available to read (e.g., out-of-band data on a socket).
• POLLOUT = Writing to the fd should accept some data now.

These are bitmask values and can be combined using the bit-wise OR operator ('|').

Parameters

[in]	monitorRef	Reference to the File Descriptor Monitor object.
[in]	events	Bit map of events.

Gets the Context Pointer for File Descriptor Monitor's handler function.

Returns

The context pointer set using le_fdMonitor_SetContextPtr(), or NULL if it hasn't been set.

Note

This only works inside the handler function. The difference between this function and le_event_GetContextPtr() is that le_fdMonitor_GetContextPtr() will double check that it's being called inside of a File Descriptor Monitor's handler function.

Gets the file descriptor that an FD Monitor object is monitoring.

Returns

The fd.

Parameters

[in]

monitorRef

Reference to the File Descriptor Monitor.

Gets a reference to the File Descriptor Monitor whose handler function is currently running.

Returns

File Descriptor Monitor reference.

Note

This only works inside the handler function.

Sets the Context Pointer for File Descriptor Monitor's handler function. This can be retrieved by the handler using le_fdMonitor_GetContextPtr() (or le_event_GetContextPtr()) when the handler function is running.

Parameters

[in]	monitorRef	Reference to the File Descriptor Monitor.
[in]	contextPtr	Opaque context pointer value.

Sets if processing of events on a given fd is deferrable (the system is allowed to go to sleep while there are monitored events pending for this fd) or urgent (the system will be kept awake until there are no monitored events waiting to be handled for this fd).

If the process has CAP_EPOLLWAKEUP (or CAP_BLOCK_SUSPEND) capability, then fd events are considered urgent by default.

If the process doesn't have CAP_EPOLLWAKEUP (or CAP_BLOCK_SUSPEND) capability, then fd events are always deferrable, and calls to this function have no effect.

Parameters

[in]	monitorRef	Reference to the File Descriptor Monitor object.
[in]	isDeferrable	true (deferrable) or false (urgent).