diff options
Diffstat (limited to 'ev.pod')
| -rw-r--r-- | ev.pod | 191 |
1 files changed, 183 insertions, 8 deletions
@@ -547,6 +547,10 @@ The signal specified in the C<ev_signal> watcher has been received by a thread. The pid specified in the C<ev_child> watcher has received a status change. +=item C<EV_STAT> + +The path specified in the C<ev_stat> watcher changed its attributes somehow. + =item C<EV_IDLE> The C<ev_idle> watcher has determined that you have nothing better to do. @@ -691,7 +695,17 @@ have been omitted.... =head1 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 I<[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 I<[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. =head2 C<ev_io> - is this file descriptor readable or writable? @@ -744,6 +758,14 @@ Configures an C<ev_io> watcher. The C<fd> is the file descriptor to rceeive events for and events is either C<EV_READ>, C<EV_WRITE> or C<EV_READ | EV_WRITE> to receive the given events. +=item int fd [read-only] + +The file descriptor being watched. + +=item int events [read-only] + +The events being watched. + =back Example: call C<stdin_readable_cb> when STDIN_FILENO has become, well @@ -816,13 +838,35 @@ 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 C<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. +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 C<ev_timer> with C<after>=C<repeat>=C<60> and calling +C<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 C<after> value and C<ev_timer_start> altogether +and only ever use the C<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. + +=item ev_tstamp repeat [read-write] + +The current C<repeat> value. Will be used each time the watcher times out +or C<ev_timer_again> is called and determines the next timeout (if any), +which is also when any modifications are taken into account. =back @@ -959,6 +1003,18 @@ when you changed some parameters or the reschedule callback would return a different time than the last time it was called (e.g. in a crond like program when the crontabs have changed). +=item ev_tstamp interval [read-write] + +The current interval value. Can be modified any time, but changes only +take effect when the periodic timer fires or C<ev_periodic_again> is being +called. + +=item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write] + +The current reschedule callback, or C<0>, if this functionality is +switched off. Can be changed any time, but changes only take effect when +the periodic timer fires or C<ev_periodic_again> is being called. + =back Example: call a callback every hour, or, more precisely, whenever the @@ -1018,6 +1074,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 C<SIGxxx> constants). +=item int signum [read-only] + +The signal the watcher watches out for. + =back @@ -1039,6 +1099,19 @@ the status word (use the macros from C<sys/wait.h> and see your systems C<waitpid> documentation). The C<rpid> member contains the pid of the process causing the status change. +=item int pid [read-only] + +The process id this watcher watches out for, or C<0>, meaning any process id. + +=item int rpid [read-write] + +The process id that detected a status change. + +=item int rstatus [read-write] + +The process exit/trace status caused by C<rpid> (see your systems +C<waitpid> and C<sys/wait.h> documentation for details). + =back Example: try to exit cleanly on SIGINT and SIGTERM. @@ -1054,6 +1127,104 @@ Example: try to exit cleanly on SIGINT and SIGTERM. ev_signal_start (loop, &sigint_cb); +=head2 C<ev_stat> - did the file attributes just change? + +This watches a filesystem path for attribute changes. That is, it calls +C<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 C<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 C<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 C<0> (highly recommended!) then a I<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 C<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. + +=over 4 + +=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) + +=item ev_stat_set (ev_stat *, const char *path, ev_tstamp interval) + +Configures the watcher to wait for status changes of the given +C<path>. The C<interval> is a hint on how quickly a change is expected to +be detected and should normally be specified as C<0> to let libev choose +a suitable value. The memory pointed to by C<path> must point to the same +path for as long as the watcher is active. + +The callback will be receive C<EV_STAT> when a change was detected, +relative to the attributes at the time the watcher was started (or the +last change was detected). + +=item 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. + +=item ev_statdata attr [read-only] + +The most-recently detected attributes of the file. Although the type is of +C<ev_statdata>, this is usually the (or one of the) C<struct stat> types +suitable for your system. If the C<st_nlink> member is C<0>, then there +was some error while C<stat>ing the file. + +=item ev_statdata prev [read-only] + +The previous attributes of the file. The callback gets invoked whenever +C<prev> != C<attr>. + +=item ev_tstamp interval [read-only] + +The specified interval. + +=item const char *path [read-only] + +The filesystem path that is being watched. + +=back + +Example: Watch C</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); + + =head2 C<ev_idle> - when you've got nothing better to do... Idle watchers trigger events when there are no other events are pending @@ -1294,6 +1465,10 @@ Make a single, non-blocking sweep over the embedded loop. This works similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most apropriate way for embedded loops. +=item struct ev_loop *loop [read-only] + +The embedded event loop. + =back |