design_notes.h File Reference

notes about btgattclient software design More...

#include <sys/epoll.h>

Go to the source code of this file.

Data Structures
struct	epoll_event_doc
	epool event structure 4th parameter of epoll_ctl(...) More...

Enumerations
enum	EPOLL_CTL_DOC { EPOLL_CTL_ADD_DOC =EPOLL_CTL_ADD, EPOLL_CTL_DEL_DOC =EPOLL_CTL_DEL, EPOLL_CTL_MOD_DOC =EPOLL_CTL_MOD }
	EPOLL_CTL_XXX possible values. More...
enum	EPOLL_EVENTS_DOC {   EPOLLERR_DOC =EPOLLERR, EPOLLET_DOC =EPOLLET, EPOLLHUP_DOC =EPOLLHUP, EPOLLIN_DOC =EPOLLIN,   EPOLLONESHOT_DOC =EPOLLONESHOT, EPOLLOUT_DOC =EPOLLOUT, EPOLLPRI_DOC =EPOLLPRI }
	EPOLL_EVENTS possible values. More...

Functions
int	epoll_ctl_doc (int epfd, int op, int fd, struct epoll_event *event)

Detailed Description

notes about btgattclient software design

We discuss about various topics concerning btgattclient software design and architecture:

• epoll: a technic, specific to Linux, to manage in a single loop various i/o events associated with files (incl. standard i/o) and sockets
• tbc: some more details to come

Author

Gilbert Brault

Copyright

Gilbert Brault 2015

Definition in file design_notes.h.

Enumeration Type Documentation

enum EPOLL_CTL_DOC

EPOLL_CTL_XXX possible values.

Enumerator
EPOLL_CTL_ADD_DOC	EPOLL_CTL_ADD: Add a monitor on the file associated with the file descriptor fd to the epoll instance associated with epfd, per the events defined in event.
EPOLL_CTL_DEL_DOC	EPOLL_CTL_DEL: Remove a monitor on the file associated with the file descriptor fd from the epoll instance associated with epfd.
EPOLL_CTL_MOD_DOC	EPOLL_CTL_MOD: Modify an existing monitor of fd with the updated events specified by event.

Definition at line 54 of file design_notes.h.

enum EPOLL_EVENTS_DOC

EPOLL_EVENTS possible values.

The events field in the epoll_event structure lists which events to monitor on the given file descriptor. Multiple events can be bitwise-ORed together.

Edge- Versus Level-Triggered Events

If the EPOLLET value is set in the events field of the event parameter passed to epoll_ctl( ),
the watch on fd is edge-triggered, as opposed to level-triggered.

Consider the following events between a producer and a consumer communicating over a Unix pipe:

    The producer writes 1 KB of data onto a pipe.

    The consumer performs an epoll_wait( ) on the pipe, waiting for the pipe to contain data, and thus be readable.

With a level-triggered watch, the call to epoll_wait( ) in step 2 will return immediately,
showing that the pipe is ready to read.

With an edge-triggered watch,this call will not return until after step 1 occurs.
That is, even if the pipe is readable at the invocation of epoll_wait( ),
the call will not return until the data is written onto the pipe.

Level-triggered is the default behavior. It is how poll( ) and select( ) behave,
and it is what most developers expect. Edge-triggered behavior requires a different approach
to programming, commonly utilizing nonblocking I/O, and careful checking for EAGAIN.

Enumerator
EPOLLERR_DOC	EPOLLERR: An error condition occurred on the file. This event is always monitored, even if it's not specified.
EPOLLET_DOC	EPOLLET: Enables edge-triggered behavior for the monitor of the file (see the upcoming section "Edge- Versus Level-Triggered Events"). The default behavior is level-triggered.
EPOLLHUP_DOC	EPOLLHUP: A hangup occurred on the file. This event is always monitored, even if it's not specified.
EPOLLIN_DOC	EPOLLIN: The file is available to be read from without blocking.
EPOLLONESHOT_DOC	EPOLLONESHOT: After an event is generated and read, the file is automatically no longer monitored. A new event mask must be specified via EPOLL_CTL_MOD to reenable the watch.
EPOLLOUT_DOC	EPOLLOUT: The file is available to be written to without blocking.
EPOLLPRI_DOC	EPOLLPRI: There is urgent out-of-band data available to read.

Definition at line 93 of file design_notes.h.

Function Documentation

int epoll_ctl_doc	(	int	epfd,
		int	op,
		int	fd,
		struct epoll_event *	event
	)

controls the epoll instance associated with epfd

Parameters

epfd	the epoll context structure
op	specifies the operation to be taken against the file associated with fd
fd	file descriptor can be a socket
event	epool event further constrains the behavior of the operation

Returns

0 success <0 error