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

Comparing libev/ev.pod (file contents):
Revision 1.57 by root, Wed Nov 28 11:27:29 2007 UTC vs.
Revision 1.61 by root, Thu Nov 29 12:21:05 2007 UTC

… …
63details of the event, and then hand it over to libev by I<starting> the 63details of the event, and then hand it over to libev by I<starting> the
64watcher. 64watcher.
65 65
66=head1 FEATURES 66=head1 FEATURES
67 67
68Libev supports C<select>, C<poll>, the linux-specific C<epoll>, the 68Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
69bsd-specific C<kqueue> and the solaris-specific event port mechanisms 69BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
70for file descriptor events (C<ev_io>), relative timers (C<ev_timer>), 70for file descriptor events (C<ev_io>), the Linux C<inotify> interface
71(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers
71absolute timers with customised rescheduling (C<ev_periodic>), synchronous 72with customised rescheduling (C<ev_periodic>), synchronous signals
72signals (C<ev_signal>), process status change events (C<ev_child>), and 73(C<ev_signal>), process status change events (C<ev_child>), and event
73event watchers dealing with the event loop mechanism itself (C<ev_idle>, 74watchers dealing with the event loop mechanism itself (C<ev_idle>,
74C<ev_embed>, C<ev_prepare> and C<ev_check> watchers) as well as 75C<ev_embed>, C<ev_prepare> and C<ev_check> watchers) as well as
75file watchers (C<ev_stat>) and even limited support for fork events 76file watchers (C<ev_stat>) and even limited support for fork events
76(C<ev_fork>). 77(C<ev_fork>).
77 78
78It also is quite fast (see this 79It also is quite fast (see this
… …
162C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for 163C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
163recommended ones. 164recommended ones.
164 165
165See the description of C<ev_embed> watchers for more info. 166See the description of C<ev_embed> watchers for more info.
166 167
167=item ev_set_allocator (void *(*cb)(void *ptr, size_t size)) 168=item ev_set_allocator (void *(*cb)(void *ptr, long size))
168 169
169Sets the allocation function to use (the prototype and semantics are 170Sets the allocation function to use (the prototype is similar - the
170identical to the realloc C function). It is used to allocate and free 171semantics is identical - to the realloc C function). It is used to
171memory (no surprises here). If it returns zero when memory needs to be 172allocate and free memory (no surprises here). If it returns zero when
172allocated, the library might abort or take some potentially destructive 173memory needs to be allocated, the library might abort or take some
173action. The default is your system realloc function. 174potentially destructive action. The default is your system realloc
175function.
174 176
175You could override this function in high-availability programs to, say, 177You could override this function in high-availability programs to, say,
176free some memory if it cannot allocate memory, to use a special allocator, 178free some memory if it cannot allocate memory, to use a special allocator,
177or even to sleep a while and retry until some memory is available. 179or even to sleep a while and retry until some memory is available.
178 180
… …
914=item ev_timer_again (loop) 916=item ev_timer_again (loop)
915 917
916This will act as if the timer timed out and restart it again if it is 918This will act as if the timer timed out and restart it again if it is
917repeating. The exact semantics are: 919repeating. The exact semantics are:
918 920
921If the timer is pending, its pending status is cleared.
922
919If the timer is started but nonrepeating, stop it. 923If the timer is started but nonrepeating, stop it (as if it timed out).
920 924
921If the timer is repeating, either start it if necessary (with the repeat 925If the timer is repeating, either start it if necessary (with the
922value), or reset the running timer to the repeat value. 926C<repeat> value), or reset the running timer to the C<repeat> value.
923 927
924This sounds a bit complicated, but here is a useful and typical 928This sounds a bit complicated, but here is a useful and typical
925example: Imagine you have a tcp connection and you want a so-called 929example: Imagine you have a tcp connection and you want a so-called idle
926idle timeout, that is, you want to be called when there have been, 930timeout, that is, you want to be called when there have been, say, 60
927say, 60 seconds of inactivity on the socket. The easiest way to do 931seconds of inactivity on the socket. The easiest way to do this is to
928this is to configure an C<ev_timer> with C<after>=C<repeat>=C<60> and calling 932configure an C<ev_timer> with a C<repeat> value of C<60> and then call
929C<ev_timer_again> each time you successfully read or write some data. If 933C<ev_timer_again> each time you successfully read or write some data. If
930you go into an idle state where you do not expect data to travel on the 934you go into an idle state where you do not expect data to travel on the
931socket, you can stop the timer, and again will automatically restart it if 935socket, you can C<ev_timer_stop> the timer, and C<ev_timer_again> will
932need be. 936automatically restart it if need be.
933 937
934You can also ignore the C<after> value and C<ev_timer_start> altogether 938That means you can ignore the C<after> value and C<ev_timer_start>
935and only ever use the C<repeat> value: 939altogether and only ever use the C<repeat> value and C<ev_timer_again>:
936 940
937 ev_timer_init (timer, callback, 0., 5.); 941 ev_timer_init (timer, callback, 0., 5.);
938 ev_timer_again (loop, timer); 942 ev_timer_again (loop, timer);
939 ... 943 ...
940 timer->again = 17.; 944 timer->again = 17.;
941 ev_timer_again (loop, timer); 945 ev_timer_again (loop, timer);
942 ... 946 ...
943 timer->again = 10.; 947 timer->again = 10.;
944 ev_timer_again (loop, timer); 948 ev_timer_again (loop, timer);
945 949
946This is more efficient then stopping/starting the timer eahc time you want 950This is more slightly efficient then stopping/starting the timer each time
947to modify its timeout value. 951you want to modify its timeout value.
948 952
949=item ev_tstamp repeat [read-write] 953=item ev_tstamp repeat [read-write]
950 954
951The current C<repeat> value. Will be used each time the watcher times out 955The current C<repeat> value. Will be used each time the watcher times out
952or C<ev_timer_again> is called and determines the next timeout (if any), 956or C<ev_timer_again> is called and determines the next timeout (if any),
… …
1220The path does not need to exist: changing from "path exists" to "path does 1224The path does not need to exist: changing from "path exists" to "path does
1221not exist" is a status change like any other. The condition "path does 1225not exist" is a status change like any other. The condition "path does
1222not exist" is signified by the C<st_nlink> field being zero (which is 1226not exist" is signified by the C<st_nlink> field being zero (which is
1223otherwise always forced to be at least one) and all the other fields of 1227otherwise always forced to be at least one) and all the other fields of
1224the stat buffer having unspecified contents. 1228the stat buffer having unspecified contents.
1229
1230The path I<should> be absolute and I<must not> end in a slash. If it is
1231relative and your working directory changes, the behaviour is undefined.
1225 1232
1226Since there is no standard to do this, the portable implementation simply 1233Since there is no standard to do this, the portable implementation simply
1227calls C<stat (2)> regularly on the path to see if it changed somehow. You 1234calls C<stat (2)> regularly on the path to see if it changed somehow. You
1228can specify a recommended polling interval for this case. If you specify 1235can specify a recommended polling interval for this case. If you specify
1229a polling interval of C<0> (highly recommended!) then a I<suitable, 1236a polling interval of C<0> (highly recommended!) then a I<suitable,

Diff Legend

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