Lines Matching refs:a

5 libev - a high performance full-featured event loop written in C
13    // a single header file is required
23    // all watcher callbacks have a similar signature
37    // another callback, this time for a time-out
57      // initialise a timer watcher, then start it
78 libev, its usage and the rationale behind its design, it is not a tutorial
95 Libev is an event loop: you register interest in certain events (such as a
96 file descriptor being readable or a timeout occurring), and it will manage
101 communicate events via a callback mechanism.
130 more info about various configuration options please have a look at
138 Libev represents time as a single floating point number, representing
154 a system call indicating a condition libev cannot fix), it calls the callback
156 abort. The default is to print a diagnostic message and to call C<abort
159 When libev detects a usage error such as a negative timer interval, then
160 it will print a diagnostic message and abort (via the C<assert> mechanism,
164 Libev also has a few internal error-checking C<assert>ions, and also has
166 circumstances, as they indicate either a bug in libev or worse.
187 passed (approximately - it might return a bit earlier even if not
190 Basically this is a sub-second-resolution C<sleep ()>.
208 Usually, it's a good idea to terminate if the major versions mismatch,
210 compatible to older versions, so a larger minor version alone is usually
211 not a problem.
226 a description of the set values.
229 a must have and can we have a torrent of it please!!!11
263 correct C<realloc> semantics, libev will use a wrapper around the system
267 free some memory if it cannot allocate memory, to use a special allocator,
268 or even to sleep a while and retry until some memory is available.
270 Example: Replace the libev allocator with one that waits a bit and then
271 retries (example requires a standards-compliant C<realloc>).
292 Set the callback function to call on a retryable system call error (such
293 as failed select, poll, epoll_wait). The message is a printable string
314 This function can be used to "simulate" a signal receive. It is completely
329 An event loop is described by a C<struct ev_loop *> (the C<struct> is
361 and to do this, it always registers a handler for C<SIGCHLD>. If this is
362 a problem for your application you can either create a dynamic loop with
378 This will create and initialise a new event loop object. If the loop
405 cannot be done in a threadsafe way, but usually it works if no other
410 Instead of calling C<ev_loop_fork> manually after a fork, you can also
411 make libev check for a fork in each iteration by enabling this flag.
414 and thus this might slow down your event loop if you do a lot of loop
416 GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
417 without a system call and thus I<very> fast, but my GNU/Linux system also has
444 there are a lot of shoddy libraries and programs (glib's threadpool for
457 It's also required by POSIX in a threaded program, as libev calls
466 but if that fails, expect a fairly low limit on the number of fds when
468 usually the fastest backend for a low number of (low-numbered :) fds.
470 To get good performance out of this backend you need a high amount of
472 writing a server, you should C<accept ()> in a loop to accept as many
474 a look at C<ev_set_io_collect_interval ()> to increase the amount of
486 considerably with a lot of inactive fds). It scales similarly to select,
498 For few fds, this backend is a bit little slower than poll and select, but
505 dropping file descriptors, requiring a system call per change per file
509 0.1ms) and so on. The biggest issue is fork races, however - if a program
523 because epoll returns immediately despite a nonzero timeout. And last
527 Epoll is truly the train wreck among event poll mechanisms, a frankenpoll,
528 cobbled together in a hurry, no thought to design or interaction with
532 will result in some caching, there is still a system call per such
533 incident (because the same I<file descriptor> could point to a different
539 watchers for a file descriptor until it has been closed, if possible,
541 starting a watcher (without re-setting it) also usually doesn't cause
547 faster than epoll for maybe up to a hundred file descriptors, depending on
565 C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
568 You still can embed kqueue into a normal poll or select backend and use it
584 almost everywhere, you should only use it when you have a lot of sockets
607 descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
611 specification in all tests and is fully embeddable, which is a rare feat
631 with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
635 C<ev_recommended_backends ()> returns, or simply do not specify a backend
640 Not a backend at all, but a mask to select all backend bits from a
641 C<flags> value, in case you want to mask out any backends from a flags
651 Example: Try to create a event loop that uses epoll and nothing else.
687 This function sets a flag that causes subsequent C<ev_run> iterations
694 In addition, if you want to reuse a loop (via this function or
698 a fork, I<even if you do not plan to use the loop in the parent>. This is
704 you just fork+exec or create a new loop in the child, you don't have to
705 call it at all (in fact, C<epoll> is so badly broken that it makes a
706 difference, but libev will usually detect this case on its own and do a
709 The function itself is quite fast and it's usually not a problem to call
710 it just in case after a fork.
735 This value can sometimes be useful as a generation counter of sorts (it
745 Outside C<ev_run>, this number is zero. In a callback, this number is
751 as a hint to avoid such ungentleman-like behaviour unless it's really
770 returned by C<ev_now ()> in the progress. This is a costly operation and
773 This function is rarely useful, but when some event callback runs for a
775 the current time is a good idea.
784 loop is not used for a while and timeouts should not be processed.
786 A typical use case would be an interactive program such as a game:  When
790 in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling
800 without a previous call to C<ev_suspend>.
822 relying on all watchers to be stopped when deciding when a program has
823 finished (especially in interactive programs), but having a program
825 of relying on its watchers stopping correctly, that is truly a thing of
828 This function is I<mostly> exception-safe - you can break out of a
829 C<ev_run> call by calling C<longjmp> in a callback, throwing a C++
842 be an event internal to libev itself, so there is no guarantee that a
848 own C<ev_run>"). However, a pair of C<ev_prepare>/C<ev_check> watchers is
849 usually a better approach for this kind of thing.
852 understanding, not a guarantee that things will work exactly like this in
859    - If EVFLAG_FORKCHECK was used, check for a fork.
860    - If a fork was detected (by any means), queue and call all fork watchers.
900 Can be used to make a call to C<ev_run> return early (but only after it
914 Ref/unref can be used to add or remove a reference count on the event
918 This is useful when you have a watcher that you never intend to
920 returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
933 Example: Create a signal watcher, but keep it from keeping C<ev_run>
955 Setting these to a higher value (the C<interval> I<must> be >= C<0>)
962 program responsive, it also wastes a lot of CPU time to poll for new
963 events, especially with backends like C<select ()> which have a high
966 By setting a higher I<io collect interval> you allow libev to spend more
969 C<ev_timer>) will not be affected. Setting this to a non-null value will
975 Likewise, by setting a higher I<timeout collect interval> you allow libev
978 later). C<ev_io> watchers will not be affected. Setting this to a non-null
982 interval to a value near C<0.1> or so, which is often enough for
984 usually doesn't make much sense to set it to a lower value than C<0.01>,
1009 function can be invoked from a watcher - this can be useful for example
1033 each call to a libev function.
1064 Set and retrieve a single C<void *> associated with a loop. When
1068 These two functions can be used to associate arbitrary data with a loop,
1095 your interest in some event. To make a concrete example, imagine you want
1116 watcher structures (and it is I<usually> a bad idea to do this on the
1122 Each watcher structure must be initialised by a call to C<ev_init (watcher
1123 *, callback)>, which expects a callback to be provided. This callback is
1130 is also a macro to combine initialisation and setting in one call: C<<
1134 with a watcher-specific start function (C<< ev_TYPE_start (loop, watcher
1143 registered watcher structure as second, and a bitset of received events as
1146 The received events usually include a single bit per event type received
1169 The signal specified in the C<ev_signal> watcher has been received by a thread.
1173 The pid specified in the C<ev_child> watcher has received a status change.
1196 they want, and all of them will be taken into account (for example, a
1226 ran out of memory, a file descriptor was found to be closed or any other
1231 an error ever, so when your watcher receives it, this usually indicates a
1234 Libev will usually signal a few "dummy" events together with an error, for
1235 example it might indicate that a fd is readable or writable, and if your
1249 This macro initialises the generic portion of a watcher. The contents
1253 type-specific parts. For each type there is also a C<ev_TYPE_init> macro
1256 You can reinitialise a watcher at any time as long as it has been stopped
1270 This macro initialises the type-specific parts of a watcher. You need to
1273 macro on a watcher that is active (it can be pending, however, which is a
1284 calls into a single call. This is the most convenient method to initialise
1285 a watcher. The same limitations apply, of course.
1310 therefore a good idea to always call its C<ev_TYPE_stop> function.
1314 Returns a true value iff the watcher is active (i.e. it has been started
1315 and not yet been stopped). As long as a watcher is active you must not modify
1320 Returns a true value iff the watcher is pending, (i.e. it has outstanding
1321 events but its callback has not yet been invoked). As long as a watcher
1340 Set and query the priority of the watcher. The priority is a small
1349 You I<must not> change the priority of a watcher as long as it is active or
1352 Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
1359 See L</WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
1375 Sometimes it can be useful to "poll" a watcher instead of waiting for its
1381 had happened for the specified watcher (which must be a pointer to an
1390 functions that do not need a watcher.
1408 Before a watcher can be registered with the event loop it has to be
1409 initialised. This can be done with a call to C<ev_TYPE_init>, or calls to
1419 Once a watcher has been started with a call to C<ev_TYPE_start> it becomes
1421 this state it cannot be accessed (except in a few documented ways), moved,
1422 freed or anything else - the only legal thing is to keep a pointer to it,
1427 If a watcher is active and libev determines that an event it is interested
1428 in has occurred (such as a timer expiring), it will become pending. It will
1440 It is also possible to feed an event on a watcher that is not active (e.g.
1449 of whether it was active or not, so stopping a watcher explicitly before
1450 freeing it is often a good idea.
1477 callback invocation within a single event loop iteration: Higher priority
1488 common case of one high-priority watcher locking out a mass of lower
1492 watchers handling the same resource: a typical usage example is having an
1497 the timer a lower priority than the I/O watcher ensures that I/O will be
1520 Here is an example of an I/O watcher that should run at a strictly lower
1556 In the "real" world, it might also be beneficial to start a timer, so that
1558 enables your program to keep a lower latency for important connections
1581 I/O watchers check whether a file descriptor is readable or writable
1591 descriptors to non-blocking mode is also usually a good idea (but not
1596 be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1598 with a relatively standard program structure. Thus it is best to always
1600 preferable to a program hanging until some data arrives.
1604 re-test whether a file descriptor is really ready with a known-to-be good
1614 Some backends (e.g. kqueue, epoll) need to be told about closing a file
1620 fact, a different file descriptor.
1624 will assume that this is potentially a new file descriptor, otherwise
1648 doesn't block on disk accesses (which can take a long time on their own).
1650 However, this cannot ever work in the "expected" way - you get a readiness
1653 always get a readiness notification instantly, and your read (or possibly
1666 usually a tty, often a pipe, but also sometimes files or special devices
1674 when you rarely read from a file instead of from a socket, and want to
1684 ()> after a fork in the child, enable C<EVFLAG_FORKCHECK>, or resort to
1690 when writing to a pipe whose other end has been closed, your program gets
1691 sent a SIGPIPE, which, by default, aborts your program. For most programs
1696 somewhere, as that would have given you a big clue).
1701 found in post-2004 Linux) have the peculiar behaviour of not removing a
1717 situation is over. While this is a form of busy waiting, no OS offers an
1724 the C<ev_io> watcher on the listening fd "for a while", which reduces CPU
1727 If your program is single-threaded, then you could also keep a dummy file
1730 close that fd, and create a new dummy fd. This will gracefully refuse
1735 opportunity for a DoS attack.
1763 attempt to read a whole line in the callback.
1782 Timer watchers are simple relative timers that generate an event after a
1789 monotonic clock option helps a lot here).
1793 might introduce a small delay, see "the special problem of being too
1797 longer true when a callback calls C<ev_run> recursively).
1803 you want to raise some error after a while.
1808 In the following, a 60 second activity timeout is assumed - a timeout that
1814 =item 1. Use a timer and stop, reinitialise and start it on activity.
1832 still not a constant-time operation.
1834 =item 2. Use a timer and re-start it with C<ev_timer_again> inactivity.
1839 To implement this, configure an C<ev_timer> with a C<repeat> value
1879 but remember the time of last activity, and check for a real timeout only
1943 providing a new value, stopping the timer and calling the callback, which
1953 =item 4. Wee, just use a double-linked list for your timeouts.
1970 starting, stopping and updating the timers, at the expense of a major
1971 complication, and having to use a constant timeout. The constant timeout
1978 Method #2 is a simple no-brain-required solution that is adequate in most
1979 situations. Method #3 requires a bit more thinking, but handles many cases
1983 Method #1 is almost always a bad idea, and buys you nothing. Method #4 is
1990 If you ask a timer to call your callback after three seconds, then
1994 process with a STOP signal for a few hours for example.
2000 loops compare timestamps with a "elapsed delay >= requested delay", but
2004 To see why, imagine a system with a clock that only offers full second
2005 resolution (think windows if you can't come up with a broken enough OS
2006 yourself). If you schedule a one-second timer at the time 500.9, then the
2007 event loop will schedule your timeout to elapse at a system time of 500
2011 501" and invoke the callback 0.1s after it was started, even though a
2027 Establishing the current time is a costly operation (it usually takes
2029 time only before and after C<ev_run> collects new events, which causes a
2042 If the event loop is suspended for a long time, you can also force an
2049 Modern systems have a variety of clocks - libev itself uses the normal
2054 on the system, so C<ev_time ()> might return a considerably different time
2055 than C<gettimeofday ()> or C<time ()>. On a GNU/Linux system, for example,
2056 a call to C<gettimeofday> might return a second count that is one higher
2057 than a directly following call to C<time>.
2061 a second or so.
2066 invoked, you will find that sometimes the callback is a bit "early".
2072 If your timeouts are based on a physical timescale (e.g. "time out this
2083 can suspend/hibernate - what happens to the clocks during such a suspend?
2085 Some quick tests made with a Linux 2.6.28 indicate that a suspend freezes
2089 was frozen for a few seconds, but the suspend time will not be counted
2090 towards C<ev_timer> when a monotonic clock source is used. The real time
2091 clock advanced as expected, but if it is used as sole clocksource, then a
2092 long suspend would be detected as a time jump by libev, and timers would
2098 The other form of suspend (job control, or sending a SIGSTOP) will see a
2100 is suspended for a very long time, and monotonic clock sources are in use,
2103 use, then libev will again assume a timejump and adjust accordingly.
2124 The timer itself will do a best-effort at avoiding drift, that is, if
2125 you configure a timer to trigger every 10 seconds, then it will normally
2151 This sounds a bit complicated, see L</Be smart about timeouts>, above, for a
2156 Returns the remaining time until a timer fires. If the timer is active,
2176 Example: Create a timer that fires after 60 seconds.
2188 Example: Create a timeout timer that times out after 10 seconds of
2209 Periodic watchers are also timers of a kind, but they are very versatile
2210 (and unfortunately a bit complex).
2219 You can tell a periodic watcher to trigger after some specific point
2220 in time: for example, if you tell a periodic watcher to trigger "in 10
2222 not a delay) and then reset your system clock to January of the previous
2223 year, then it will take a year or more to trigger the event (unlike an
2225 it, as it uses a relative timeout).
2236 (but this is no longer true when a callback calls C<ev_run> recursively).
2254 time C<offset> has passed. It will not repeat and will not adjust when a
2273 but only that the callback will be called when the system time shows a
2284 at most a similar magnitude as the current time (say, within a factor of
2288 Note also that there is an upper limit to how often a timer can fire (CPU
2322 NOTE: I<< This callback must always return a time that is higher than or
2325 This can be used to create very complex timers, such as a timer that
2337 a different time than the last time it was called (e.g. in a crond like
2372 Example: Call a callback every hour, or, more precisely, whenever the
2374 potentially a lot of jitter, but good long-term stability.
2379      ... its now a full hour (UTC, or TAI or whatever your clock follows)
2386 Example: The same as above, but use a reschedule callback to do it:
2398 Example: Call a callback every hour, starting now:
2406 =head2 C<ev_signal> - signal me when a signal gets signalled!
2408 Signal watchers will trigger an event when the process receives a specific
2415 the signal. You can even use C<ev_async> from a signal handler to
2424 Only after the first watcher for a signal is started will libev actually
2430 not be unduly interrupted. If you have a problem with system calls getting
2437 (C<sigaction>) are unspecified after starting a signal watcher (and after
2448 the signal mask to whatever "default" you expect (all clear is a good
2452 to install a fork handler with C<pthread_atfork> that resets it. That will
2461 you expect it to be empty, you have a race condition in your code>. This
2462 is not a libev-specific thing, this is true for most event libraries.
2467 a lot of functionality (sigfd, sigwait etc.) only really works if all
2468 threads in a process block signals, which is hard to achieve.
2472 all signals before creating any threads (or creating them with a fully set
2512 Child watchers trigger when your process receives a SIGCHLD in response to
2513 some child status changes (most typically when a child of yours dies or
2514 exits). It is permissible to install a child watcher I<after> the child
2516 as the event loop isn't entered (or is continued from a watcher), i.e.,
2517 forking and then immediately registering a watcher for the child is fine,
2518 but forking and registering a watcher a few event loop iterations later or
2552 when a child exit is detected (calling C<ev_child_stop> twice is not a
2578 The process id that detected a status change.
2589 Example: C<fork()> a new process and install a child handler to wait for
2619 This watches a file system path for attribute changes. That is, it calls
2626 not exist" is a status change like any other. The condition "path does not
2632 The path I<must not> end in a slash or contain special components such as
2638 to see if it changed somehow. You can specify a recommended polling
2639 interval for this case. If you specify a polling interval of C<0> (highly
2640 recommended!) then a I<suitable, unspecified default> value will be used
2642 change dynamically). Libev will also impose a minimum interval which is
2652 implementing C<ev_stat> semantics with kqueue, except as a hint).
2684 a local filesystem (libev currently assumes only ext2/3, jfs, reiserfs and
2688 implement this functionality, due to the requirement of having a file
2692 =head3 C<stat ()> is a synchronous operation
2696 ()>, which is a synchronous operation.
2699 busy or the intervals between stat's are large, a stat call will be fast,
2704 time due to network issues, and even under good conditions, a stat call
2717 easily miss updates: on the first update, C<ev_stat> detects a change and
2722 The solution to this is to delay acting on a change for slightly more
2723 than a second (or till slightly after the next full second boundary), using
2724 a roughly one-second-delay C<ev_timer> (e.g. C<ev_timer_set (w, 0., 1.02);
2729 might be be delayed. One such system is the Linux kernel, where a call to
2730 C<gettimeofday> might return a timestamp with a full second later than
2731 a subsequent C<time> call - if the equivalent of C<time ()> is used to
2732 update file times then there will be a small window where the kernel uses
2745 C<path>. The C<interval> is a hint on how quickly a change is expected to
2747 a suitable value. The memory pointed to by C<path> must point to the same
2750 The callback will receive an C<EV_STAT> event when a change was detected,
2758 detecting this change (while introducing a race condition if you are not
2813 Example: Like above, but additionally use a one-second delay so we do not
2858 Apart from keeping your process non-blocking (which is a useful
2859 effect on its own sometimes), idle watchers are a good place to do
2874 See L</Abusing an ev_check watcher for its side-effect> for a longer
2884 kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
2928 variable changes, implement your own watchers, integrate net-snmp or a
2969 example, if you want to handle a large number of connections fairly, you
2970 normally only do a bit of work for each active connection, and if there
2972 connections have a chance of making progress.
2978 This is where C<ev_idle> watchers come in handy - all you need is a
2981 will not sleep, and the C<ev_check> watcher makes sure a callback gets
3001 There are a number of principal ways to embed other event loops or modules
3003 (there is a Perl module named C<EV::ADNS> that does this, which you could
3004 use as a working example. Another Perl module named C<EV::Glib> embeds a
3008 Method 1: Add IO watchers and a timeout watcher in a prepare handler,
3009 and in a check watcher, destroy them and call into libadns. What follows
3010 is pseudo-code only of course. This requires you to either use a low
3022    // create io watchers for each fd and a timer before blocking
3097 Method 4: Do not use a prepare or check watcher because the module you
3101 this approach, effectively embedding EV as a client into the horrible
3132 This is a rather advanced watcher type that lets you embed one event loop
3134 loop, other types of watchers might be handled in a delayed or incorrect
3140 As an example for a bug workaround, the kqueue backend might only support
3143 so nicely. In this case, you would create a kqueue-based loop and embed
3145 will be a bit slower because first libev has to call C<poll> and then
3153 the rest in a second one, and embed the second one in the first.
3157 must then call C<ev_embed_sweep (mainloop, watcher)> to make a single
3176 this is to have a separate variables for your embeddable loop, try to
3203 Make a single, non-blocking sweep over the embedded loop. This works
3225    // see if there is a chance of getting one that works
3226    // (remember that a flags value of 0 means autodetection)
3241 a kqueue backend for use with sockets (which usually work with any
3262 =head2 C<ev_fork> - the audacity to resume the event loop after a fork
3264 Fork watchers are called when a C<fork ()> was detected (usually because
3265 whoever is a good citizen cared to tell libev about it by calling
3275 up/change the process environment, followed by a call to C<exec()>. This
3292 simply create a new event loop, which of course will be "empty", and
3313 kind. There is a C<ev_fork_set> macro, but using it is utterly pointless,
3322 by a call to C<ev_loop_destroy>.
3325 watchers provide a convenient method to install cleanup hooks for your
3330 all other watchers, they do not keep a reference to the event loop (which
3331 makes a lot of sense if you think about it). Like all other watchers, you
3341 any kind. There is a C<ev_cleanup_set> macro, but using it is utterly
3373 C<ev_async_send> calls). In fact, you could use signal watchers as a kind
3374 of "global async watchers" by using a watcher on an otherwise unused
3381 is that the author does not know of a simple (or any) algorithm for a
3392 =item queueing from a signal handler context
3431 =item queueing from a thread context
3435 employ a traditional mutex lock, such as in this pthread example:
3472 kind. There is a C<ev_async_set> macro, but using it is utterly pointless,
3486 compressed into a single callback invocation (another way to look at
3499 Returns a non-zero value when C<ev_async_send> has been called on the
3503 C<ev_async_send> sets a flag in the watcher and wakes up the loop. When
3506 quickly check whether invoking the loop might be a good idea.
3510 is a time window between the event loop checking and resetting the async
3524 This function combines a simple timer and an I/O watcher, calls your
3526 watchers. This is useful if you want to wait for a single event on an fd
3536 repeat = 0) will be started. C<0> is a valid timeout.
3539 passed an C<revents> set like normal event callbacks (a combination of
3542 a timeout and an io event at the same time - you probably should give io
3559 Feed an event on the given fd, as if a file descriptor backend detected
3578 Each watcher has, by default, a C<void *data> member that you can read
3581 don't want to allocate memory separately and store a pointer to it in that
3597 And since your callback will be called with a pointer to the watcher, you
3622 In this case getting the pointer to C<my_biggy> is a bit more
3674 delay invoking the callback by using a C<prepare> or C<idle> watcher for
3690 This brings the problem of exiting - a callback might want to finish the
3692 a modal "Are you sure?" dialog is still waiting), or just the nested one
3693 and not the main one (e.g. user clocked "Ok" in a modal dialog), or some
3694 other combination: In these cases, a simple C<ev_break> will not work.
3697 invocation, and use a loop around C<ev_run> until the condition is
3706    // in a modal watcher
3725 Here is a fictitious example of how to run an event loop in a different
3729 For a real-world example, see the C<EV::Loop::Async> perl module,
3733 The example uses a pthread mutex to protect the loop data, a condition
3748       // for simplicity, we use a static userdata struct.
3812 have been called (in a while loop because a) spurious wakeups are possible
3843 Whenever you want to start/stop a watcher or do other modifications to an
3863 While the overhead of a callback that e.g. schedules a thread is small, it
3868 Imagine you have coroutines that you can switch to using a function
3869 C<switch_to (coro)>, that libev runs in a coroutine called C<libev_coro>
3870 and that due to some magic, the currently active coroutine is stored in a
3878 That means instead of having a C callback function, you store the
3882 A coroutine might now wait for an event with a function called
3899 instead of storing a coroutine, you store the queue object and instead of
3900 switching to a coroutine, you push the watcher onto the queue and notify
3922 Libev offers a compatibility emulation layer for libevent. It cannot
3939 it a private API).
3966 reschedule callbacks) must not throw exceptions, and might need a C<throw
3985 is compiled with a C++ compiler or your C and C++ environments allow
3992 the callback model to a model using method callbacks on objects.
4018 Here is a list of things available in the C<ev> namespace:
4033 For each C<ev_TYPE> watcher in F<ev.h> there is a corresponding class of
4054 It will not set a callback, however: You have to call the templated C<set>
4055 method to set a callback before you can start the watcher.
4057 (The reason why you have to use a method is a limitation in C++ which does
4064 This method sets the callback method to call. The method has to have a
4073 thunking function, making it as fast as a direct C callback.
4088 This is a variation of a method callback - leaving out the method to call
4099 Example: use a functor object as callback.
4116 Also sets a callback, but uses a static method or plain function as
4124 Example: Use a plain function as callback.
4131 Associates a different C<struct ev_loop> with this watcher. You can only
4137 with the same arguments. Either this method or a suitable start method
4177 Example: Define a class with two I/O and idle watchers, start the I/O
4202 Libev does not offer other language bindings itself, but bindings for a
4205 me a note.
4228 Tony Arcieri has written a ruby extension that offers access to a subset
4243 Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
4253 Brian Maher has written a partial interface to libev for lua (at the
4270 Libev can be compiled with a variety of options, the most fundamental
4304 It declares a parameter C<loop> of type C<struct ev_loop *>, quite
4320 is undefined when the default loop has not been initialised by a previous
4324 watcher in a function but use C<EV_DEFAULT_UC> afterwards.
4328 Example: Declare and initialise a check watcher, utilising the above
4351 source directory without having to change even a single line in them, so
4352 you can easily upgrade by simply copying (or having a checked-out copy of
4368 This will automatically include F<ev.h>, too, and should be done in a
4371 done by writing a wrapper around F<ev.h> that you can include instead and
4377 Both header files and implementation files can be compiled with a C++
4378 compiler (at least, that's a stated goal, and breakage will be treated
4379 as a bug).
4381 You need the following files in your source tree, or in a directory
4430 Libev can be configured via a variety of preprocessor symbols you have to
4437 to a compiled library. All other symbols change the ABI, which means all
4445 Backwards compatibility is a major concern for libev. This is why this
4473 periodic reschedule calculations, otherwise libev will fall back on a
4502 If defined to be C<1>, libev will try to use a direct syscall instead
4506 programs needlessly. Using a direct syscall is slightly slower (in
4534 structure. This is useful if libev doesn't compile due to a missing
4553 If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
4634 different threads (that includes signal handlers), which is a stronger
4682 Note that C<EV_DEFAULT> and C<EV_DEFAULT_> will no longer provide a
4696 all the priorities, so having many of them (hundreds) uses a lot of space
4718 A typical way to use this symbol is to define it to C<0> (or to a bitset
4730 The actual value is a bitset, it can be a combination of the following
4743 gcc is recommended, as well as C<-DNDEBUG>, as libev contains a number of
4751 Replaces the small 2-heap for timer management by a faster 4-heap, larger
4766 This enables a lot of the "lesser used" API functions. See C<ev.h> for
4780 least one backend manually (C<EV_USE_SELECT> is a good choice).
4796 your program might be left out as well - a binary starting a timer and an
4804 when you embed libev, only want to use libev functions in a single file,
4810 This option only works when libev is compiled with a C compiler, as C++
4829 specified. Also, using a lower number than detected (C<32> should be
4835 C<ev_child> watchers use a small hash table to distribute workload by
4838 might want to increase this value (I<must> be a power of two).
4842 C<ev_stat> watchers use a small hash table to distribute workload by
4845 C<ev_stat> watchers you might want to increase this value (I<must> be a
4851 timer and periodics heaps, libev uses a 4-heap when this symbol is defined
4863 which uses 8-12 bytes more per watcher and a few hundred bytes more code,
4885 By default, all watchers have a C<void *data> member. By redefining
4903 and the way callbacks are invoked and set. Must expand to a struct member
4904 definition and a statement, respectively. See the F<ev.h> header file for
4913 If you need to re-export the API (e.g. via a DLL) and you need a list of
4929 This would create a file F<wrap.h> which essentially looks like this:
4938 For a real-world example of a program the includes libev
4939 verbatim, you can have a look at the EV perl module
4946 The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
4960 And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
4982 only one thread ever is inside a call at any point in time, e.g. by using
4983 a mutex per loop).
4996 =item * most applications have a main thread: use the default libev loop
4997 in that thread, or create a separate thread running only the default loop.
5002 =item * one loop per thread is usually a good model.
5004 Doing this is almost never wrong, sometimes a better-performance model
5005 exists, but it is always a good start.
5008 loop is handed through multiple threads in a kind of round-robin fashion.
5010 Choosing a model is hard - look around, learn, know that usually you can do
5043 Depending on your compiler and compiler settings, you might get no or a
5049 warning options. "Warn-free" code therefore cannot be a goal except when
5050 targeting a specific compiler and compiler-version.
5064 "warn-free" code is not a goal, and it is recommended not to build libev
5072 Valgrind has a special section here because it is a popular tool that is
5075 If you think you found a bug (memory leak, uninitialised data access etc.)
5083 is not a memleak - the memory is still being referenced, and didn't leak.
5086 as if it were a bug in libev (e.g. in realloc or in the poll backend,
5090 Keep in mind that valgrind is a very good tool, but only a tool. Don't
5095 is a bug in libev (best check the archives, too :). However, don't be
5096 annoyed when you get a brisk "this is no bug" answer and take the chance
5123 The whole thing is a bug if you ask me - basically any system interface
5133 rotten platform, but of course you can still ask for it when creating a
5134 loop - embedding a socket-only kqueue loop into a select-based one is
5145 a loop.
5149 All that's left is C<select>, and of course Apple found a way to fuck this
5164 without C<-D_REENTRANT> in a threaded program, which, of course, isn't
5175 a large number of spurious wakeups, make sure you have all the relevant
5186 AIX unfortunately has a broken C<poll.h> header. Libev works around
5188 compiled in), which normally isn't a big problem as C<select> works fine
5201 as every compiler comes with a slightly differently broken/incompatible
5206 then note that glib does exactly that for you in a very portable way (note
5215 Not a libev limitation but worth mentioning: windows apparently doesn't
5216 accept large writes: instead of resulting in a partial write, windows will
5218 so make sure you only write small amounts into your sockets (less than a
5223 the abysmal performance of winsockets, using a large number of sockets
5225 more than a hundred or so sockets, then likely it needs to use a totally
5250 requires a mapping from file descriptors to socket handles (the Microsoft
5255 The configuration for a "naked" win32 using the Microsoft runtime
5261 Note that winsockets handling of fd sets is O(n), so you can easily get a
5268 Early versions of winsocket's select only supported waiting for a maximum
5271 recommends spawning a chain of threads and wait for 63 handles and the
5280 libraries, which by default is C<64> (there must be a hidden I<64>
5291 In addition to a working ISO-C implementation and of course the
5292 backend-specific APIs, libev relies on a few additional extensions:
5307 Accessing a pointer value must be atomic, it must both be readable and
5317 =item C<sigprocmask> must work in a threaded environment
5320 allowed in a threaded program (C<pthread_sigmask> has to be used). Typical
5338 =item C<double> must hold a time value in seconds with enough accuracy
5353 If you know of other additional requirements drop me a note.
5365 mean that libev does a lengthy realloc operation in rare cases, but on
5372 This means that, when you have a watcher that triggers in one hour and
5378 That means that changing a timer costs less than removing/adding them,
5383 These just add the watcher into an array or at the head of a list.
5396 By virtue of using a binary or 4-heap, the next timer is always found at a
5399 =item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
5420 Sending involves a system call I<iff> there were no other C<ev_async_send>
5481 The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
5507 The address of a function that is called when some event has been
5513 The act of calling the callback associated with a watcher.
5518 for reading on a file descriptor, time having passed or simply not having