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

Comparing libev/ev.pod (file contents):
Revision 1.265 by root, Wed Aug 26 17:11:42 2009 UTC vs.
Revision 1.277 by root, Thu Dec 31 06:50:17 2009 UTC

… …
118Libev is very configurable. In this manual the default (and most common) 118Libev is very configurable. In this manual the default (and most common)
119configuration will be described, which supports multiple event loops. For 119configuration will be described, which supports multiple event loops. For
120more info about various configuration options please have a look at 120more info about various configuration options please have a look at
121B<EMBED> section in this manual. If libev was configured without support 121B<EMBED> section in this manual. If libev was configured without support
122for multiple event loops, then all functions taking an initial argument of 122for multiple event loops, then all functions taking an initial argument of
123name C<loop> (which is always of type C<ev_loop *>) will not have 123name C<loop> (which is always of type C<struct ev_loop *>) will not have
124this argument. 124this argument.
125 125
126=head2 TIME REPRESENTATION 126=head2 TIME REPRESENTATION
127 127
128Libev represents time as a single floating point number, representing 128Libev represents time as a single floating point number, representing
… …
370When this flag is specified, then libev will not attempt to use the 370When this flag is specified, then libev will not attempt to use the
371I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and 371I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
372testing, this flag can be useful to conserve inotify file descriptors, as 372testing, this flag can be useful to conserve inotify file descriptors, as
373otherwise each loop using C<ev_stat> watchers consumes one inotify handle. 373otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
374 374
375=item C<EVFLAG_NOSIGNALFD> 375=item C<EVFLAG_SIGNALFD>
376 376
377When this flag is specified, then libev will not attempt to use the 377When this flag is specified, then libev will attempt to use the
378I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This is 378I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
379probably only useful to work around any bugs in libev. Consequently, this 379delivers signals synchronously, which makes is both faster and might make
380flag might go away once the signalfd functionality is considered stable, 380it possible to get the queued signal data.
381so it's useful mostly in environment variables and not in program code. 381
382Signalfd will not be used by default as this changes your signal mask, and
383there are a lot of shoddy libraries and programs (glib's threadpool for
384example) that can't properly initialise their signal masks.
382 385
383=item C<EVBACKEND_SELECT> (value 1, portable select backend) 386=item C<EVBACKEND_SELECT> (value 1, portable select backend)
384 387
385This is your standard select(2) backend. Not I<completely> standard, as 388This is your standard select(2) backend. Not I<completely> standard, as
386libev tries to roll its own fd_set with no limits on the number of fds, 389libev tries to roll its own fd_set with no limits on the number of fds,
… …
410 413
411This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and 414This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
412C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>. 415C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
413 416
414=item C<EVBACKEND_EPOLL> (value 4, Linux) 417=item C<EVBACKEND_EPOLL> (value 4, Linux)
418
419Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9
420kernels).
415 421
416For few fds, this backend is a bit little slower than poll and select, 422For few fds, this backend is a bit little slower than poll and select,
417but it scales phenomenally better. While poll and select usually scale 423but it scales phenomenally better. While poll and select usually scale
418like O(total_fds) where n is the total number of fds (or the highest fd), 424like O(total_fds) where n is the total number of fds (or the highest fd),
419epoll scales either O(1) or O(active_fds). 425epoll scales either O(1) or O(active_fds).
… …
590as signal and child watchers) would need to be stopped manually. 596as signal and child watchers) would need to be stopped manually.
591 597
592In general it is not advisable to call this function except in the 598In general it is not advisable to call this function except in the
593rare occasion where you really need to free e.g. the signal handling 599rare occasion where you really need to free e.g. the signal handling
594pipe fds. If you need dynamically allocated loops it is better to use 600pipe fds. If you need dynamically allocated loops it is better to use
595C<ev_loop_new> and C<ev_loop_destroy>). 601C<ev_loop_new> and C<ev_loop_destroy>.
596 602
597=item ev_loop_destroy (loop) 603=item ev_loop_destroy (loop)
598 604
599Like C<ev_default_destroy>, but destroys an event loop created by an 605Like C<ev_default_destroy>, but destroys an event loop created by an
600earlier call to C<ev_loop_new>. 606earlier call to C<ev_loop_new>.
… …
704event loop time (see C<ev_now_update>). 710event loop time (see C<ev_now_update>).
705 711
706=item ev_loop (loop, int flags) 712=item ev_loop (loop, int flags)
707 713
708Finally, this is it, the event handler. This function usually is called 714Finally, this is it, the event handler. This function usually is called
709after you initialised all your watchers and you want to start handling 715after you have initialised all your watchers and you want to start
710events. 716handling events.
711 717
712If the flags argument is specified as C<0>, it will not return until 718If the flags argument is specified as C<0>, it will not return until
713either no event watchers are active anymore or C<ev_unloop> was called. 719either no event watchers are active anymore or C<ev_unloop> was called.
714 720
715Please note that an explicit C<ev_unloop> is usually better than 721Please note that an explicit C<ev_unloop> is usually better than
… …
789 795
790Ref/unref can be used to add or remove a reference count on the event 796Ref/unref can be used to add or remove a reference count on the event
791loop: Every watcher keeps one reference, and as long as the reference 797loop: Every watcher keeps one reference, and as long as the reference
792count is nonzero, C<ev_loop> will not return on its own. 798count is nonzero, C<ev_loop> will not return on its own.
793 799
794If you have a watcher you never unregister that should not keep C<ev_loop> 800This is useful when you have a watcher that you never intend to
795from returning, call ev_unref() after starting, and ev_ref() before 801unregister, but that nevertheless should not keep C<ev_loop> from
802returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
796stopping it. 803before stopping it.
797 804
798As an example, libev itself uses this for its internal signal pipe: It 805As an example, libev itself uses this for its internal signal pipe: It
799is not visible to the libev user and should not keep C<ev_loop> from 806is not visible to the libev user and should not keep C<ev_loop> from
800exiting if no event watchers registered by it are active. It is also an 807exiting if no event watchers registered by it are active. It is also an
801excellent way to do this for generic recurring timers or from within 808excellent way to do this for generic recurring timers or from within
… …
916 923
917While event loop modifications are allowed between invocations of 924While event loop modifications are allowed between invocations of
918C<release> and C<acquire> (that's their only purpose after all), no 925C<release> and C<acquire> (that's their only purpose after all), no
919modifications done will affect the event loop, i.e. adding watchers will 926modifications done will affect the event loop, i.e. adding watchers will
920have no effect on the set of file descriptors being watched, or the time 927have no effect on the set of file descriptors being watched, or the time
921waited. USe an C<ev_async> watcher to wake up C<ev_loop> when you want it 928waited. Use an C<ev_async> watcher to wake up C<ev_loop> when you want it
922to take note of any changes you made. 929to take note of any changes you made.
923 930
924In theory, threads executing C<ev_loop> will be async-cancel safe between 931In theory, threads executing C<ev_loop> will be async-cancel safe between
925invocations of C<release> and C<acquire>. 932invocations of C<release> and C<acquire>.
926 933
… …
1123 1130
1124 ev_io w; 1131 ev_io w;
1125 ev_init (&w, my_cb); 1132 ev_init (&w, my_cb);
1126 ev_io_set (&w, STDIN_FILENO, EV_READ); 1133 ev_io_set (&w, STDIN_FILENO, EV_READ);
1127 1134
1128=item C<ev_TYPE_set> (ev_TYPE *, [args]) 1135=item C<ev_TYPE_set> (ev_TYPE *watcher, [args])
1129 1136
1130This macro initialises the type-specific parts of a watcher. You need to 1137This macro initialises the type-specific parts of a watcher. You need to
1131call C<ev_init> at least once before you call this macro, but you can 1138call C<ev_init> at least once before you call this macro, but you can
1132call C<ev_TYPE_set> any number of times. You must not, however, call this 1139call C<ev_TYPE_set> any number of times. You must not, however, call this
1133macro on a watcher that is active (it can be pending, however, which is a 1140macro on a watcher that is active (it can be pending, however, which is a
… …
1146 1153
1147Example: Initialise and set an C<ev_io> watcher in one step. 1154Example: Initialise and set an C<ev_io> watcher in one step.
1148 1155
1149 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); 1156 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
1150 1157
1151=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 1158=item C<ev_TYPE_start> (loop, ev_TYPE *watcher)
1152 1159
1153Starts (activates) the given watcher. Only active watchers will receive 1160Starts (activates) the given watcher. Only active watchers will receive
1154events. If the watcher is already active nothing will happen. 1161events. If the watcher is already active nothing will happen.
1155 1162
1156Example: Start the C<ev_io> watcher that is being abused as example in this 1163Example: Start the C<ev_io> watcher that is being abused as example in this
1157whole section. 1164whole section.
1158 1165
1159 ev_io_start (EV_DEFAULT_UC, &w); 1166 ev_io_start (EV_DEFAULT_UC, &w);
1160 1167
1161=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) 1168=item C<ev_TYPE_stop> (loop, ev_TYPE *watcher)
1162 1169
1163Stops the given watcher if active, and clears the pending status (whether 1170Stops the given watcher if active, and clears the pending status (whether
1164the watcher was active or not). 1171the watcher was active or not).
1165 1172
1166It is possible that stopped watchers are pending - for example, 1173It is possible that stopped watchers are pending - for example,
… …
1191=item ev_cb_set (ev_TYPE *watcher, callback) 1198=item ev_cb_set (ev_TYPE *watcher, callback)
1192 1199
1193Change the callback. You can change the callback at virtually any time 1200Change the callback. You can change the callback at virtually any time
1194(modulo threads). 1201(modulo threads).
1195 1202
1196=item ev_set_priority (ev_TYPE *watcher, priority) 1203=item ev_set_priority (ev_TYPE *watcher, int priority)
1197 1204
1198=item int ev_priority (ev_TYPE *watcher) 1205=item int ev_priority (ev_TYPE *watcher)
1199 1206
1200Set and query the priority of the watcher. The priority is a small 1207Set and query the priority of the watcher. The priority is a small
1201integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> 1208integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
… …
1232returns its C<revents> bitset (as if its callback was invoked). If the 1239returns its C<revents> bitset (as if its callback was invoked). If the
1233watcher isn't pending it does nothing and returns C<0>. 1240watcher isn't pending it does nothing and returns C<0>.
1234 1241
1235Sometimes it can be useful to "poll" a watcher instead of waiting for its 1242Sometimes it can be useful to "poll" a watcher instead of waiting for its
1236callback to be invoked, which can be accomplished with this function. 1243callback to be invoked, which can be accomplished with this function.
1244
1245=item ev_feed_event (loop, ev_TYPE *watcher, int revents)
1246
1247Feeds the given event set into the event loop, as if the specified event
1248had happened for the specified watcher (which must be a pointer to an
1249initialised but not necessarily started event watcher). Obviously you must
1250not free the watcher as long as it has pending events.
1251
1252Stopping the watcher, letting libev invoke it, or calling
1253C<ev_clear_pending> will clear the pending event, even if the watcher was
1254not started in the first place.
1255
1256See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
1257functions that do not need a watcher.
1237 1258
1238=back 1259=back
1239 1260
1240 1261
1241=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 1262=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
… …
1837C<repeat> value), or reset the running timer to the C<repeat> value. 1858C<repeat> value), or reset the running timer to the C<repeat> value.
1838 1859
1839This sounds a bit complicated, see L<Be smart about timeouts>, above, for a 1860This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1840usage example. 1861usage example.
1841 1862
1842=item ev_timer_remaining (loop, ev_timer *) 1863=item ev_tstamp ev_timer_remaining (loop, ev_timer *)
1843 1864
1844Returns the remaining time until a timer fires. If the timer is active, 1865Returns the remaining time until a timer fires. If the timer is active,
1845then this time is relative to the current event loop time, otherwise it's 1866then this time is relative to the current event loop time, otherwise it's
1846the timeout value currently configured. 1867the timeout value currently configured.
1847 1868
… …
2114C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should 2135C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
2115not be unduly interrupted. If you have a problem with system calls getting 2136not be unduly interrupted. If you have a problem with system calls getting
2116interrupted by signals you can block all signals in an C<ev_check> watcher 2137interrupted by signals you can block all signals in an C<ev_check> watcher
2117and unblock them in an C<ev_prepare> watcher. 2138and unblock them in an C<ev_prepare> watcher.
2118 2139
2119=head3 The special problem of inheritance over execve 2140=head3 The special problem of inheritance over fork/execve/pthread_create
2120 2141
2121Both the signal mask (C<sigprocmask>) and the signal disposition 2142Both the signal mask (C<sigprocmask>) and the signal disposition
2122(C<sigaction>) are unspecified after starting a signal watcher (and after 2143(C<sigaction>) are unspecified after starting a signal watcher (and after
2123stopping it again), that is, libev might or might not block the signal, 2144stopping it again), that is, libev might or might not block the signal,
2124and might or might not set or restore the installed signal handler. 2145and might or might not set or restore the installed signal handler.
2125 2146
2126While this does not matter for the signal disposition (libev never 2147While this does not matter for the signal disposition (libev never
2127sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on 2148sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
2128C<execve>), this matters for the signal mask: many programs do not expect 2149C<execve>), this matters for the signal mask: many programs do not expect
2129many signals to be blocked. 2150certain signals to be blocked.
2130 2151
2131This means that before calling C<exec> (from the child) you should reset 2152This means that before calling C<exec> (from the child) you should reset
2132the signal mask to whatever "default" you expect (all clear is a good 2153the signal mask to whatever "default" you expect (all clear is a good
2133choice usually). 2154choice usually).
2155
2156The simplest way to ensure that the signal mask is reset in the child is
2157to install a fork handler with C<pthread_atfork> that resets it. That will
2158catch fork calls done by libraries (such as the libc) as well.
2159
2160In current versions of libev, the signal will not be blocked indefinitely
2161unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
2162the window of opportunity for problems, it will not go away, as libev
2163I<has> to modify the signal mask, at least temporarily.
2164
2165So I can't stress this enough I<if you do not reset your signal mask
2166when you expect it to be empty, you have a race condition in your
2167program>. This is not a libev-specific thing, this is true for most event
2168libraries.
2134 2169
2135=head3 Watcher-Specific Functions and Data Members 2170=head3 Watcher-Specific Functions and Data Members
2136 2171
2137=over 4 2172=over 4
2138 2173
… …
2955=head3 Queueing 2990=head3 Queueing
2956 2991
2957C<ev_async> does not support queueing of data in any way. The reason 2992C<ev_async> does not support queueing of data in any way. The reason
2958is that the author does not know of a simple (or any) algorithm for a 2993is that the author does not know of a simple (or any) algorithm for a
2959multiple-writer-single-reader queue that works in all cases and doesn't 2994multiple-writer-single-reader queue that works in all cases and doesn't
2960need elaborate support such as pthreads. 2995need elaborate support such as pthreads or unportable memory access
2996semantics.
2961 2997
2962That means that if you want to queue data, you have to provide your own 2998That means that if you want to queue data, you have to provide your own
2963queue. But at least I can tell you how to implement locking around your 2999queue. But at least I can tell you how to implement locking around your
2964queue: 3000queue:
2965 3001
… …
3123 /* doh, nothing entered */; 3159 /* doh, nothing entered */;
3124 } 3160 }
3125 3161
3126 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3162 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3127 3163
3128=item ev_feed_event (struct ev_loop *, watcher *, int revents)
3129
3130Feeds the given event set into the event loop, as if the specified event
3131had happened for the specified watcher (which must be a pointer to an
3132initialised but not necessarily started event watcher).
3133
3134=item ev_feed_fd_event (struct ev_loop *, int fd, int revents) 3164=item ev_feed_fd_event (loop, int fd, int revents)
3135 3165
3136Feed an event on the given fd, as if a file descriptor backend detected 3166Feed an event on the given fd, as if a file descriptor backend detected
3137the given events it. 3167the given events it.
3138 3168
3139=item ev_feed_signal_event (struct ev_loop *loop, int signum) 3169=item ev_feed_signal_event (loop, int signum)
3140 3170
3141Feed an event as if the given signal occurred (C<loop> must be the default 3171Feed an event as if the given signal occurred (C<loop> must be the default
3142loop!). 3172loop!).
3143 3173
3144=back 3174=back
… …
3224 3254
3225=over 4 3255=over 4
3226 3256
3227=item ev::TYPE::TYPE () 3257=item ev::TYPE::TYPE ()
3228 3258
3229=item ev::TYPE::TYPE (struct ev_loop *) 3259=item ev::TYPE::TYPE (loop)
3230 3260
3231=item ev::TYPE::~TYPE 3261=item ev::TYPE::~TYPE
3232 3262
3233The constructor (optionally) takes an event loop to associate the watcher 3263The constructor (optionally) takes an event loop to associate the watcher
3234with. If it is omitted, it will use C<EV_DEFAULT>. 3264with. If it is omitted, it will use C<EV_DEFAULT>.
… …
3311Example: Use a plain function as callback. 3341Example: Use a plain function as callback.
3312 3342
3313 static void io_cb (ev::io &w, int revents) { } 3343 static void io_cb (ev::io &w, int revents) { }
3314 iow.set <io_cb> (); 3344 iow.set <io_cb> ();
3315 3345
3316=item w->set (struct ev_loop *) 3346=item w->set (loop)
3317 3347
3318Associates a different C<struct ev_loop> with this watcher. You can only 3348Associates a different C<struct ev_loop> with this watcher. You can only
3319do this when the watcher is inactive (and not pending either). 3349do this when the watcher is inactive (and not pending either).
3320 3350
3321=item w->set ([arguments]) 3351=item w->set ([arguments])

Diff Legend

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