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

Comparing libev/ev.pod (file contents):
Revision 1.142 by root, Sun Apr 6 09:53:18 2008 UTC vs.
Revision 1.145 by root, Wed Apr 9 22:07:50 2008 UTC

… …
196See the description of C<ev_embed> watchers for more info. 196See the description of C<ev_embed> watchers for more info.
197 197
198=item ev_set_allocator (void *(*cb)(void *ptr, long size)) 198=item ev_set_allocator (void *(*cb)(void *ptr, long size))
199 199
200Sets the allocation function to use (the prototype is similar - the 200Sets the allocation function to use (the prototype is similar - the
201semantics is identical - to the realloc C function). It is used to 201semantics are identical to the C<realloc> C89/SuS/POSIX function). It is
202allocate and free memory (no surprises here). If it returns zero when 202used to allocate and free memory (no surprises here). If it returns zero
203memory needs to be allocated, the library might abort or take some 203when memory needs to be allocated (C<size != 0>), the library might abort
204potentially destructive action. The default is your system realloc 204or take some potentially destructive action.
205function. 205
206Since some systems (at least OpenBSD and Darwin) fail to implement
207correct C<realloc> semantics, libev will use a wrapper around the system
208C<realloc> and C<free> functions by default.
206 209
207You could override this function in high-availability programs to, say, 210You could override this function in high-availability programs to, say,
208free some memory if it cannot allocate memory, to use a special allocator, 211free some memory if it cannot allocate memory, to use a special allocator,
209or even to sleep a while and retry until some memory is available. 212or even to sleep a while and retry until some memory is available.
210 213
211Example: Replace the libev allocator with one that waits a bit and then 214Example: Replace the libev allocator with one that waits a bit and then
212retries). 215retries (example requires a standards-compliant C<realloc>).
213 216
214 static void * 217 static void *
215 persistent_realloc (void *ptr, size_t size) 218 persistent_realloc (void *ptr, size_t size)
216 { 219 {
217 for (;;) 220 for (;;)
… …
255=head1 FUNCTIONS CONTROLLING THE EVENT LOOP 258=head1 FUNCTIONS CONTROLLING THE EVENT LOOP
256 259
257An event loop is described by a C<struct ev_loop *>. The library knows two 260An event loop is described by a C<struct ev_loop *>. The library knows two
258types of such loops, the I<default> loop, which supports signals and child 261types of such loops, the I<default> loop, which supports signals and child
259events, and dynamically created loops which do not. 262events, and dynamically created loops which do not.
260
261If you use threads, a common model is to run the default event loop
262in your main thread (or in a separate thread) and for each thread you
263create, you also create another event loop. Libev itself does no locking
264whatsoever, so if you mix calls to the same event loop in different
265threads, make sure you lock (this is usually a bad idea, though, even if
266done correctly, because it's hideous and inefficient).
267 263
268=over 4 264=over 4
269 265
270=item struct ev_loop *ev_default_loop (unsigned int flags) 266=item struct ev_loop *ev_default_loop (unsigned int flags)
271 267
… …
2633=item C<EV_DEFAULT>, C<EV_DEFAULT_> 2629=item C<EV_DEFAULT>, C<EV_DEFAULT_>
2634 2630
2635Similar to the other two macros, this gives you the value of the default 2631Similar to the other two macros, this gives you the value of the default
2636loop, if multiple loops are supported ("ev loop default"). 2632loop, if multiple loops are supported ("ev loop default").
2637 2633
2634=item C<EV_DEFAULT_UC>, C<EV_DEFAULT_UC_>
2635
2636Usage identical to C<EV_DEFAULT> and C<EV_DEFAULT_>, but requires that the
2637default loop has been initialised (C<UC> == unchecked). Their behaviour
2638is undefined when the default loop has not been initialised by a previous
2639execution of C<EV_DEFAULT>, C<EV_DEFAULT_> or C<ev_default_init (...)>.
2640
2641It is often prudent to use C<EV_DEFAULT> when initialising the first
2642watcher in a function but use C<EV_DEFAULT_UC> afterwards.
2643
2638=back 2644=back
2639 2645
2640Example: Declare and initialise a check watcher, utilising the above 2646Example: Declare and initialise a check watcher, utilising the above
2641macros so it will work regardless of whether multiple loops are supported 2647macros so it will work regardless of whether multiple loops are supported
2642or not. 2648or not.
… …
3057 3063
3058 #include "ev_cpp.h" 3064 #include "ev_cpp.h"
3059 #include "ev.c" 3065 #include "ev.c"
3060 3066
3061 3067
3068=head1 THREADS AND COROUTINES
3069
3070=head2 THREADS
3071
3072Libev itself is completely threadsafe, but it uses no locking. This
3073means that you can use as many loops as you want in parallel, as long as
3074only one thread ever calls into one libev function with the same loop
3075parameter.
3076
3077Or put differently: calls with different loop parameters can be done in
3078parallel from multiple threads, calls with the same loop parameter must be
3079done serially (but can be done from different threads, as long as only one
3080thread ever is inside a call at any point in time, e.g. by using a mutex
3081per loop).
3082
3083If you want to know which design is best for your problem, then I cannot
3084help you but by giving some generic advice:
3085
3086=over 4
3087
3088=item * most applications have a main thread: use the default libev loop
3089in that thread, or create a seperate thread running only the default loop.
3090
3091This helps integrating other libraries or software modules that use libev
3092themselves and don't care/know about threading.
3093
3094=item * one loop per thread is usually a good model.
3095
3096Doing this is almost never wrong, sometimes a better-performance model
3097exists, but it is always a good start.
3098
3099=item * other models exist, such as the leader/follower pattern, where one
3100loop is handed through multiple threads in a kind of round-robbin fashion.
3101
3102Chosing a model is hard - look around, learn, know that usually you cna do
3103better than you currently do :-)
3104
3105=item * often you need to talk to some other thread which blocks in the
3106event loop - C<ev_async> watchers can be used to wake them up from other
3107threads safely (or from signal contexts...).
3108
3109=back
3110
3111=head2 COROUTINES
3112
3113Libev is much more accomodating to coroutines ("cooperative threads"):
3114libev fully supports nesting calls to it's functions from different
3115coroutines (e.g. you can call C<ev_loop> on the same loop from two
3116different coroutines and switch freely between both coroutines running the
3117loop, as long as you don't confuse yourself). The only exception is that
3118you must not do this from C<ev_periodic> reschedule callbacks.
3119
3120Care has been invested into making sure that libev does not keep local
3121state inside C<ev_loop>, and other calls do not usually allow coroutine
3122switches.
3123
3124
3062=head1 COMPLEXITIES 3125=head1 COMPLEXITIES
3063 3126
3064In this section the complexities of (many of) the algorithms used inside 3127In this section the complexities of (many of) the algorithms used inside
3065libev will be explained. For complexity discussions about backends see the 3128libev will be explained. For complexity discussions about backends see the
3066documentation for C<ev_default_init>. 3129documentation for C<ev_default_init>.

Diff Legend

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