WATCHER TYPES

This section describes each watcher in detail, but will not repeat -information given in the last section.

+information given in the last section. Any initialisation/set macros, +functions and members specific to the watcher type are explained.

Members are additionally marked with either [read-only], meaning that, +while the watcher is active, you can look at the member and expect some +sensible content, but you must not modify it (you can modify it while the +watcher is stopped to your hearts content), or [read-write], which +means you can expect it to have some sensible content while the watcher +is active, but you can also modify it. Modifying it may not do something +sensible or take immediate effect (or do anything at all), but libev will +not crash or malfunction in any way.

@@ -782,6 +797,14 @@ its own, so its quite safe to use).

rceeive events for and events is either EV_READ, EV_WRITE or EV_READ | EV_WRITE to receive the given events.

Example: call stdin_readable_cb when STDIN_FILENO has become, well readable, but only once. Since it is likely line-buffered, you could @@ -848,13 +871,34 @@ repeating. The exact semantics are:

If the timer is repeating, either start it if necessary (with the repeat value), or reset the running timer to the repeat value.

This sounds a bit complicated, but here is a useful and typical -example: Imagine you have a tcp connection and you want a so-called idle -timeout, that is, you want to be called when there have been, say, 60 -seconds of inactivity on the socket. The easiest way to do this is to -configure an ev_timer with after=repeat=60 and calling ev_timer_again each -time you successfully read or write some data. If you go into an idle -state where you do not expect data to travel on the socket, you can stop -the timer, and again will automatically restart it if need be.

You can also ignore the after value and ev_timer_start altogether +and only ever use the repeat value:

ev_timer_init (timer, callback, 0., 5.); + ev_timer_again (loop, timer); + ... + timer->again = 17.; + ev_timer_again (loop, timer); + ... + timer->again = 10.; + ev_timer_again (loop, timer); + +

This is more efficient then stopping/starting the timer eahc time you want +to modify its timeout value.

Example: call a callback every hour, or, more precisely, whenever the system clock is divisible by 3600. The callback invocation times have @@ -1040,6 +1096,10 @@ SIG_DFL (regardless of what it was set to before).

Configures the watcher to trigger on the given signal number (usually one of the SIGxxx constants).

ev_stat - did the file attributes just change?

This watches a filesystem path for attribute changes. That is, it calls +stat regularly (or when the OS says it changed) and sees if it changed +compared to the last time, invoking the callback if it did.

The path does not need to exist: changing from "path exists" to "path does +not exist" is a status change like any other. The condition "path does +not exist" is signified by the st_nlink field being zero (which is +otherwise always forced to be at least one) and all the other fields of +the stat buffer having unspecified contents.

Since there is no standard to do this, the portable implementation simply +calls stat (2) regulalry on the path to see if it changed somehow. You +can specify a recommended polling interval for this case. If you specify +a polling interval of 0 (highly recommended!) then a suitable, +unspecified default value will be used (which you can expect to be around +five seconds, although this might change dynamically). Libev will also +impose a minimum interval which is currently around 0.1, but thats +usually overkill.

This watcher type is not meant for massive numbers of stat watchers, +as even with OS-supported change notifications, this can be +resource-intensive.

At the time of this writing, no specific OS backends are implemented, but +if demand increases, at least a kqueue and inotify backend will be added.

ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)

ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)

Configures the watcher to wait for status changes of the given +path. The interval is a hint on how quickly a change is expected to +be detected and should normally be specified as 0 to let libev choose +a suitable value. The memory pointed to by path must point to the same +path for as long as the watcher is active.

The callback will be receive EV_STAT when a change was detected, +relative to the attributes at the time the watcher was started (or the +last change was detected).

ev_stat_stat (ev_stat *)

Updates the stat buffer immediately with new values. If you change the +watched path in your callback, you could call this fucntion to avoid +detecting this change (while introducing a race condition). Can also be +useful simply to find out the new values.

ev_statdata attr [read-only]

The most-recently detected attributes of the file. Although the type is of +ev_statdata, this is usually the (or one of the) struct stat types +suitable for your system. If the st_nlink member is 0, then there +was some error while stating the file.

ev_statdata prev [read-only]

The previous attributes of the file. The callback gets invoked whenever +prev != attr.

ev_tstamp interval [read-only]

The specified interval.

const char *path [read-only]

The filesystem path that is being watched.

Example: Watch /etc/passwd for attribute changes.

  static void
+  passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
+  {
+    /* /etc/passwd changed in some way */
+    if (w->attr.st_nlink)
+      {
+        printf ("passwd current size  %ld\n", (long)w->attr.st_size);
+        printf ("passwd current atime %ld\n", (long)w->attr.st_mtime);
+        printf ("passwd current mtime %ld\n", (long)w->attr.st_mtime);
+      }
+    else
+      /* you shalt not abuse printf for puts */
+      puts ("wow, /etc/passwd is not there, expect problems. "
+            "if this is windows, they already arrived\n");
+  }
+
+  ...
+  ev_stat passwd;
+
+  ev_stat_init (&passwd, passwd_cb, "/etc/passwd");
+  ev_stat_start (loop, &passwd);
+
+
+
+

COMPLEXITIES

In this section the complexities of (many of) the algorithms used inside +libev will be explained. For complexity discussions about backends see the +documentation for ev_default_init.

Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)
Starting io/check/prepare/idle/signal/child watchers: O(1)
Stopping check/prepare/idle watchers: O(1)
Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % 16))
Finding the next timer per loop iteration: O(1)
Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
Activating one watcher: O(1)

+ + + + +

WATCHER TYPES

`ev_stat` - did the file attributes just change?

COMPLEXITIES

AUTHOR

WATCHER TYPES

ev_stat - did the file attributes just change?

COMPLEXITIES

AUTHOR

`ev_stat` - did the file attributes just change?