ANATOMY OF A WATCHER

ANATOMY OF A WATCHER

A watcher is a structure that you create and register to record your interest in some event. For instance, if you want to wait for STDIN to become readable, you would create an ev_io watcher for that.

static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents) { ev_io_stop (w); ev_break (loop, EVUNLOOP_ALL); } struct ev_loop *loop = ev_default_loop (0); struct ev_io stdin_watcher; ev_init (&stdin_watcher, my_cb); ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ); ev_io_start (loop, &stdin_watcher); ev_run (loop, 0);

Each watcher structure must be initialized by a call to ev_init(watcher*, callback), which expects a callback to be provides. This callback gets invoked each time the event occurs. 

Each watcher type has its own ev_set(watcher *, ...) macro with arguments specific to this watcher type.

There is also a macro to combine initialization and setting in one call: ev__init(watcher*, callback, ...).

To make the watcher actually watch out for events, you have to start it with a watcher-specific start function ev__start(loop, watcher*), and you can stop watching for events at any time by calling the corresponding stop function ev__stop(loop, watcher*).

The possible events bit masks

• EV_READ
  
• EV_WRITE
• The file descriptor in the ev_io watcher has become readable and/or writable.
• EV_TIMEOUT
• The ev_timer watcher has timed out.
• EV_PERIODIC
• The ev_periodic watcher has time out.
• EV_SIGNAL
• The signal specified in the ev_signal watcher has been received by a thread.
• EV_CHILD
• The pid specified in the ev_child watcher has received a status change.
• EV_START
• The path specified in the ev_stat watcher changed its attributes somehow.
• EV_IDLE
• The ev_idle watcher has determined that you have nothing better to do.
• EV_PREPARE
• EV_CHECK
• All ev_prepare watchers are invoked just before ev_loop starts to gather new events.
• All ev_check watchers are invoked just after ev_loop has gathered them, but before it invokes any callbacks for any received events.
• EV_EMBED
• The embeded event loop specified in the ev_embed watcher needs attenion.
• EV_FORK
• The events loop ahs been resumed in the child process after fork.
• EV_ASYNC
• The given async watcher has been asynchronously notified.
• EV_ERROR
• An unspecified error has occured, the watcher has been stopped.

Generic Watcher functions

ev_init(ev_type *watcher ,callback)

• This macro initializes the generic portion of a watcher.
• The callback is always of type void (*)(ev_loop* loop, ev_TYPE* watcher, int revents).

ev_type_set(ev_TYPE*, [args])

• This macro initializes the type-specific parts of a watcher
• You need to call ev_init at least once before you call this macro.

ev_TYPE_init(ev_TYPE *watcher, callback, [args])

• This macro rolls both ev_init and ev_TYPE_set macro calls into a sigle call.

ev_TYPE_start(loop *, ev_TYPE *watcher)

• Starts the given watcher.

ev_TYPE_stop(loop *, ev_TYPE *watcher)

• Stops the given watcher again and clears the pending status.

reference: http://doc.dvgu.ru/devel/ev.html#anatomy_of_a_watcher