le_fdMonitor.h File Reference

Go to the source code of this file.

Typedefs
typedef struct le_fdMonitor *	le_fdMonitor_Ref_t
typedef void(*	le_fdMonitor_HandlerFunc_t) (int fd, short events)

Functions
le_fdMonitor_Ref_t	le_fdMonitor_Create (const char *name, int fd, le_fdMonitor_HandlerFunc_t handlerFunc, short events)
void	le_fdMonitor_Enable (le_fdMonitor_Ref_t monitorRef, short events)
void	le_fdMonitor_Disable (le_fdMonitor_Ref_t monitorRef, short events)
void	le_fdMonitor_SetDeferrable (le_fdMonitor_Ref_t monitorRef, bool isDeferrable)
void	le_fdMonitor_SetContextPtr (le_fdMonitor_Ref_t monitorRef, void *contextPtr)
void *	le_fdMonitor_GetContextPtr (void)
le_fdMonitor_Ref_t	le_fdMonitor_GetMonitor (void)
void	le_fdMonitor_Delete (le_fdMonitor_Ref_t monitorRef)

Detailed Description

Legato File Descriptor Monitor API include file.

Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.

Typedef Documentation

typedef void(* le_fdMonitor_HandlerFunc_t) (int fd, short events)

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.

typedef struct le_fdMonitor* le_fdMonitor_Ref_t

File Descriptor Monitor reference.

Used to refer to File Descriptor Monitor objects.

Function Documentation

le_fdMonitor_Ref_t le_fdMonitor_Create	(	const char *	name,
		int	fd,
		le_fdMonitor_HandlerFunc_t	handlerFunc,
		short	events
	)

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.

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.

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.

void le_fdMonitor_Delete

(

le_fdMonitor_Ref_t

monitorRef

)

Deletes a file descriptor monitor object.

Parameters

[in]

monitorRef

Reference to the File Descriptor Monitor object.

void le_fdMonitor_Disable	(	le_fdMonitor_Ref_t	monitorRef,
		short	events
	)

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.

void le_fdMonitor_Enable	(	le_fdMonitor_Ref_t	monitorRef,
		short	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.

void* le_fdMonitor_GetContextPtr

(

void

)

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.

le_fdMonitor_Ref_t le_fdMonitor_GetMonitor

(

void

)

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.

void le_fdMonitor_SetContextPtr	(	le_fdMonitor_Ref_t	monitorRef,
		void *	contextPtr
	)

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.

void le_fdMonitor_SetDeferrable	(	le_fdMonitor_Ref_t	monitorRef,
		bool	isDeferrable
	)

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).