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

Comparing libev/ev.pod (file contents):
Revision 1.261 by root, Mon Jul 20 04:18:20 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
2108 2129
2109When the first watcher gets started will libev actually register something 2130When the first watcher gets started will libev actually register something
2110with the kernel (thus it coexists with your own signal handlers as long as 2131with the kernel (thus it coexists with your own signal handlers as long as
2111you don't register any with libev for the same signal). 2132you don't register any with libev for the same signal).
2112 2133
2113Both the signal mask state (C<sigprocmask>) and the signal handler state
2114(C<sigaction>) are unspecified after starting a signal watcher (and after
2115sotpping it again), that is, libev might or might not block the signal,
2116and might or might not set or restore the installed signal handler.
2117
2118If possible and supported, libev will install its handlers with 2134If possible and supported, libev will install its handlers with
2119C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should 2135C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
2120not 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
2121interrupted 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
2122and unblock them in an C<ev_prepare> watcher. 2138and unblock them in an C<ev_prepare> watcher.
2139
2140=head3 The special problem of inheritance over fork/execve/pthread_create
2141
2142Both the signal mask (C<sigprocmask>) and the signal disposition
2143(C<sigaction>) are unspecified after starting a signal watcher (and after
2144stopping it again), that is, libev might or might not block the signal,
2145and might or might not set or restore the installed signal handler.
2146
2147While this does not matter for the signal disposition (libev never
2148sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
2149C<execve>), this matters for the signal mask: many programs do not expect
2150certain signals to be blocked.
2151
2152This means that before calling C<exec> (from the child) you should reset
2153the signal mask to whatever "default" you expect (all clear is a good
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.
2123 2169
2124=head3 Watcher-Specific Functions and Data Members 2170=head3 Watcher-Specific Functions and Data Members
2125 2171
2126=over 4 2172=over 4
2127 2173
2944=head3 Queueing 2990=head3 Queueing
2945 2991
2946C<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
2947is 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
2948multiple-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
2949need elaborate support such as pthreads. 2995need elaborate support such as pthreads or unportable memory access
2996semantics.
2950 2997
2951That 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
2952queue. 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
2953queue: 3000queue:
2954 3001
3112 /* doh, nothing entered */; 3159 /* doh, nothing entered */;
3113 } 3160 }
3114 3161
3115 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3162 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3116 3163
3117=item ev_feed_event (struct ev_loop *, watcher *, int revents)
3118
3119Feeds the given event set into the event loop, as if the specified event
3120had happened for the specified watcher (which must be a pointer to an
3121initialised but not necessarily started event watcher).
3122
3123=item ev_feed_fd_event (struct ev_loop *, int fd, int revents) 3164=item ev_feed_fd_event (loop, int fd, int revents)
3124 3165
3125Feed 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
3126the given events it. 3167the given events it.
3127 3168
3128=item ev_feed_signal_event (struct ev_loop *loop, int signum) 3169=item ev_feed_signal_event (loop, int signum)
3129 3170
3130Feed 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
3131loop!). 3172loop!).
3132 3173
3133=back 3174=back
3213 3254
3214=over 4 3255=over 4
3215 3256
3216=item ev::TYPE::TYPE () 3257=item ev::TYPE::TYPE ()
3217 3258
3218=item ev::TYPE::TYPE (struct ev_loop *) 3259=item ev::TYPE::TYPE (loop)
3219 3260
3220=item ev::TYPE::~TYPE 3261=item ev::TYPE::~TYPE
3221 3262
3222The constructor (optionally) takes an event loop to associate the watcher 3263The constructor (optionally) takes an event loop to associate the watcher
3223with. If it is omitted, it will use C<EV_DEFAULT>. 3264with. If it is omitted, it will use C<EV_DEFAULT>.
3300Example: Use a plain function as callback. 3341Example: Use a plain function as callback.
3301 3342
3302 static void io_cb (ev::io &w, int revents) { } 3343 static void io_cb (ev::io &w, int revents) { }
3303 iow.set <io_cb> (); 3344 iow.set <io_cb> ();
3304 3345
3305=item w->set (struct ev_loop *) 3346=item w->set (loop)
3306 3347
3307Associates 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
3308do this when the watcher is inactive (and not pending either). 3349do this when the watcher is inactive (and not pending either).
3309 3350
3310=item w->set ([arguments]) 3351=item w->set ([arguments])
3407=item Ocaml 3448=item Ocaml
3408 3449
3409Erkki Seppala has written Ocaml bindings for libev, to be found at 3450Erkki Seppala has written Ocaml bindings for libev, to be found at
3410L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 3451L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
3411 3452
3453=item Lua
3454
3455Brian Maher has written a partial interface to libev
3456for lua (only C<ev_io> and C<ev_timer>), to be found at
3457L<http://github.com/brimworks/lua-ev>.
3458
3412=back 3459=back
3413 3460
3414 3461
3415=head1 MACRO MAGIC 3462=head1 MACRO MAGIC
3416 3463
3582keeps libev from including F<config.h>, and it also defines dummy 3629keeps libev from including F<config.h>, and it also defines dummy
3583implementations for some libevent functions (such as logging, which is not 3630implementations for some libevent functions (such as logging, which is not
3584supported). It will also not define any of the structs usually found in 3631supported). It will also not define any of the structs usually found in
3585F<event.h> that are not directly supported by the libev core alone. 3632F<event.h> that are not directly supported by the libev core alone.
3586 3633
3587In stanbdalone mode, libev will still try to automatically deduce the 3634In standalone mode, libev will still try to automatically deduce the
3588configuration, but has to be more conservative. 3635configuration, but has to be more conservative.
3589 3636
3590=item EV_USE_MONOTONIC 3637=item EV_USE_MONOTONIC
3591 3638
3592If defined to be C<1>, libev will try to detect the availability of the 3639If defined to be C<1>, libev will try to detect the availability of the
3657be used is the winsock select). This means that it will call 3704be used is the winsock select). This means that it will call
3658C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise, 3705C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
3659it is assumed that all these functions actually work on fds, even 3706it is assumed that all these functions actually work on fds, even
3660on win32. Should not be defined on non-win32 platforms. 3707on win32. Should not be defined on non-win32 platforms.
3661 3708
3662=item EV_FD_TO_WIN32_HANDLE 3709=item EV_FD_TO_WIN32_HANDLE(fd)
3663 3710
3664If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map 3711If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
3665file descriptors to socket handles. When not defining this symbol (the 3712file descriptors to socket handles. When not defining this symbol (the
3666default), then libev will call C<_get_osfhandle>, which is usually 3713default), then libev will call C<_get_osfhandle>, which is usually
3667correct. In some cases, programs use their own file descriptor management, 3714correct. In some cases, programs use their own file descriptor management,
3668in which case they can provide this function to map fds to socket handles. 3715in which case they can provide this function to map fds to socket handles.
3716
3717=item EV_WIN32_HANDLE_TO_FD(handle)
3718
3719If C<EV_SELECT_IS_WINSOCKET> then libev maps handles to file descriptors
3720using the standard C<_open_osfhandle> function. For programs implementing
3721their own fd to handle mapping, overwriting this function makes it easier
3722to do so. This can be done by defining this macro to an appropriate value.
3723
3724=item EV_WIN32_CLOSE_FD(fd)
3725
3726If programs implement their own fd to handle mapping on win32, then this
3727macro can be used to override the C<close> function, useful to unregister
3728file descriptors again. Note that the replacement function has to close
3729the underlying OS handle.
3669 3730
3670=item EV_USE_POLL 3731=item EV_USE_POLL
3671 3732
3672If defined to be C<1>, libev will compile in support for the C<poll>(2) 3733If defined to be C<1>, libev will compile in support for the C<poll>(2)
3673backend. Otherwise it will be enabled on non-win32 platforms. It 3734backend. Otherwise it will be enabled on non-win32 platforms. It

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines