ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.107 by root, Mon Dec 24 04:34:00 2007 UTC vs.
Revision 1.110 by root, Tue Dec 25 07:05:45 2007 UTC

… …
983In general you can register as many read and/or write event watchers per 983In general you can register as many read and/or write event watchers per
984fd as you want (as long as you don't confuse yourself). Setting all file 984fd as you want (as long as you don't confuse yourself). Setting all file
985descriptors to non-blocking mode is also usually a good idea (but not 985descriptors to non-blocking mode is also usually a good idea (but not
986required if you know what you are doing). 986required if you know what you are doing).
987 987
988You have to be careful with dup'ed file descriptors, though. Some backends
989(the linux epoll backend is a notable example) cannot handle dup'ed file
990descriptors correctly if you register interest in two or more fds pointing
991to the same underlying file/socket/etc. description (that is, they share
992the same underlying "file open").
993
994If you must do this, then force the use of a known-to-be-good backend 988If you must do this, then force the use of a known-to-be-good backend
995(at the time of this writing, this includes only C<EVBACKEND_SELECT> and 989(at the time of this writing, this includes only C<EVBACKEND_SELECT> and
996C<EVBACKEND_POLL>). 990C<EVBACKEND_POLL>).
997 991
998Another thing you have to watch out for is that it is quite easy to 992Another thing you have to watch out for is that it is quite easy to
… …
1033 1027
1034=head3 The special problem of dup'ed file descriptors 1028=head3 The special problem of dup'ed file descriptors
1035 1029
1036Some backends (e.g. epoll), cannot register events for file descriptors, 1030Some backends (e.g. epoll), cannot register events for file descriptors,
1037but only events for the underlying file descriptions. That means when you 1031but only events for the underlying file descriptions. That means when you
1038have C<dup ()>'ed file descriptors and register events for them, only one 1032have C<dup ()>'ed file descriptors or weirder constellations, and register
1039file descriptor might actually receive events. 1033events for them, only one file descriptor might actually receive events.
1040 1034
1041There is no workaround possible except not registering events 1035There is no workaround possible except not registering events
1042for potentially C<dup ()>'ed file descriptors, or to resort to 1036for potentially C<dup ()>'ed file descriptors, or to resort to
1043C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>. 1037C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
1044 1038
… …
1496semantics of C<ev_stat> watchers, which means that libev sometimes needs 1490semantics of C<ev_stat> watchers, which means that libev sometimes needs
1497to fall back to regular polling again even with inotify, but changes are 1491to fall back to regular polling again even with inotify, but changes are
1498usually detected immediately, and if the file exists there will be no 1492usually detected immediately, and if the file exists there will be no
1499polling. 1493polling.
1500 1494
1495=head3 Inotify
1496
1497When C<inotify (7)> support has been compiled into libev (generally only
1498available on Linux) and present at runtime, it will be used to speed up
1499change detection where possible. The inotify descriptor will be created lazily
1500when the first C<ev_stat> watcher is being started.
1501
1502Inotify presense does not change the semantics of C<ev_stat> watchers
1503except that changes might be detected earlier, and in some cases, to avoid
1504making regular C<stat> calls. Even in the presense of inotify support
1505there are many cases where libev has to resort to regular C<stat> polling.
1506
1507(There is no support for kqueue, as apparently it cannot be used to
1508implement this functionality, due to the requirement of having a file
1509descriptor open on the object at all times).
1510
1501=head3 The special problem of stat time resolution 1511=head3 The special problem of stat time resolution
1502 1512
1503The C<stat ()> syscall only supports full-second resolution portably, and 1513The C<stat ()> syscall only supports full-second resolution portably, and
1504even on systems where the resolution is higher, many filesystems still 1514even on systems where the resolution is higher, many filesystems still
1505only support whole seconds. 1515only support whole seconds.
… …
1559=item const char *path [read-only] 1569=item const char *path [read-only]
1560 1570
1561The filesystem path that is being watched. 1571The filesystem path that is being watched.
1562 1572
1563=back 1573=back
1574
1575=head3 Examples
1564 1576
1565Example: Watch C</etc/passwd> for attribute changes. 1577Example: Watch C</etc/passwd> for attribute changes.
1566 1578
1567 static void 1579 static void
1568 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents) 1580 passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
… …
2483be detected at runtime. 2495be detected at runtime.
2484 2496
2485=item EV_H 2497=item EV_H
2486 2498
2487The name of the F<ev.h> header file used to include it. The default if 2499The name of the F<ev.h> header file used to include it. The default if
2488undefined is C<< <ev.h> >> in F<event.h> and C<"ev.h"> in F<ev.c>. This 2500undefined is C<"ev.h"> in F<event.h> and F<ev.c>. This can be used to
2489can be used to virtually rename the F<ev.h> header file in case of conflicts. 2501virtually rename the F<ev.h> header file in case of conflicts.
2490 2502
2491=item EV_CONFIG_H 2503=item EV_CONFIG_H
2492 2504
2493If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 2505If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
2494F<ev.c>'s idea of where to find the F<config.h> file, similarly to 2506F<ev.c>'s idea of where to find the F<config.h> file, similarly to
2495C<EV_H>, above. 2507C<EV_H>, above.
2496 2508
2497=item EV_EVENT_H 2509=item EV_EVENT_H
2498 2510
2499Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 2511Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
2500of how the F<event.h> header can be found. 2512of how the F<event.h> header can be found, the dfeault is C<"event.h">.
2501 2513
2502=item EV_PROTOTYPES 2514=item EV_PROTOTYPES
2503 2515
2504If defined to be C<0>, then F<ev.h> will not define any function 2516If defined to be C<0>, then F<ev.h> will not define any function
2505prototypes, but still define all the structs and other symbols. This is 2517prototypes, but still define all the structs and other symbols. This is

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines