… | |
… | |
4 | |
4 | |
5 | =head1 SYNOPSIS |
5 | =head1 SYNOPSIS |
6 | |
6 | |
7 | #include <ev.h> |
7 | #include <ev.h> |
8 | |
8 | |
9 | =head1 EXAMPLE PROGRAM |
9 | =head2 EXAMPLE PROGRAM |
10 | |
10 | |
11 | #include <ev.h> |
11 | #include <ev.h> |
12 | |
12 | |
13 | ev_io stdin_watcher; |
13 | ev_io stdin_watcher; |
14 | ev_timer timeout_watcher; |
14 | ev_timer timeout_watcher; |
… | |
… | |
65 | You register interest in certain events by registering so-called I<event |
65 | You register interest in certain events by registering so-called I<event |
66 | watchers>, which are relatively small C structures you initialise with the |
66 | watchers>, which are relatively small C structures you initialise with the |
67 | details of the event, and then hand it over to libev by I<starting> the |
67 | details of the event, and then hand it over to libev by I<starting> the |
68 | watcher. |
68 | watcher. |
69 | |
69 | |
70 | =head1 FEATURES |
70 | =head2 FEATURES |
71 | |
71 | |
72 | Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the |
72 | Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the |
73 | BSD-specific C<kqueue> and the Solaris-specific event port mechanisms |
73 | BSD-specific C<kqueue> and the Solaris-specific event port mechanisms |
74 | for file descriptor events (C<ev_io>), the Linux C<inotify> interface |
74 | for file descriptor events (C<ev_io>), the Linux C<inotify> interface |
75 | (for C<ev_stat>), relative timers (C<ev_timer>), absolute timers |
75 | (for C<ev_stat>), relative timers (C<ev_timer>), absolute timers |
… | |
… | |
82 | |
82 | |
83 | It also is quite fast (see this |
83 | It also is quite fast (see this |
84 | L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent |
84 | L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent |
85 | for example). |
85 | for example). |
86 | |
86 | |
87 | =head1 CONVENTIONS |
87 | =head2 CONVENTIONS |
88 | |
88 | |
89 | Libev is very configurable. In this manual the default configuration will |
89 | Libev is very configurable. In this manual the default configuration will |
90 | be described, which supports multiple event loops. For more info about |
90 | be described, which supports multiple event loops. For more info about |
91 | various configuration options please have a look at B<EMBED> section in |
91 | various configuration options please have a look at B<EMBED> section in |
92 | this manual. If libev was configured without support for multiple event |
92 | this manual. If libev was configured without support for multiple event |
93 | loops, then all functions taking an initial argument of name C<loop> |
93 | loops, then all functions taking an initial argument of name C<loop> |
94 | (which is always of type C<struct ev_loop *>) will not have this argument. |
94 | (which is always of type C<struct ev_loop *>) will not have this argument. |
95 | |
95 | |
96 | =head1 TIME REPRESENTATION |
96 | =head2 TIME REPRESENTATION |
97 | |
97 | |
98 | Libev represents time as a single floating point number, representing the |
98 | Libev represents time as a single floating point number, representing the |
99 | (fractional) number of seconds since the (POSIX) epoch (somewhere near |
99 | (fractional) number of seconds since the (POSIX) epoch (somewhere near |
100 | the beginning of 1970, details are complicated, don't ask). This type is |
100 | the beginning of 1970, details are complicated, don't ask). This type is |
101 | called C<ev_tstamp>, which is what you should use too. It usually aliases |
101 | called C<ev_tstamp>, which is what you should use too. It usually aliases |
… | |
… | |
983 | In general you can register as many read and/or write event watchers per |
983 | In general you can register as many read and/or write event watchers per |
984 | fd as you want (as long as you don't confuse yourself). Setting all file |
984 | fd as you want (as long as you don't confuse yourself). Setting all file |
985 | descriptors to non-blocking mode is also usually a good idea (but not |
985 | descriptors to non-blocking mode is also usually a good idea (but not |
986 | required if you know what you are doing). |
986 | required if you know what you are doing). |
987 | |
987 | |
988 | You have to be careful with dup'ed file descriptors, though. Some backends |
|
|
989 | (the linux epoll backend is a notable example) cannot handle dup'ed file |
|
|
990 | descriptors correctly if you register interest in two or more fds pointing |
|
|
991 | to the same underlying file/socket/etc. description (that is, they share |
|
|
992 | the same underlying "file open"). |
|
|
993 | |
|
|
994 | If you must do this, then force the use of a known-to-be-good backend |
988 | If you must do this, then force the use of a known-to-be-good backend |
995 | (at the time of this writing, this includes only C<EVBACKEND_SELECT> and |
989 | (at the time of this writing, this includes only C<EVBACKEND_SELECT> and |
996 | C<EVBACKEND_POLL>). |
990 | C<EVBACKEND_POLL>). |
997 | |
991 | |
998 | Another thing you have to watch out for is that it is quite easy to |
992 | Another thing you have to watch out for is that it is quite easy to |
… | |
… | |
1033 | |
1027 | |
1034 | =head3 The special problem of dup'ed file descriptors |
1028 | =head3 The special problem of dup'ed file descriptors |
1035 | |
1029 | |
1036 | Some backends (e.g. epoll), cannot register events for file descriptors, |
1030 | Some backends (e.g. epoll), cannot register events for file descriptors, |
1037 | but only events for the underlying file descriptions. That means when you |
1031 | but only events for the underlying file descriptions. That means when you |
1038 | have C<dup ()>'ed file descriptors and register events for them, only one |
1032 | have C<dup ()>'ed file descriptors or weirder constellations, and register |
1039 | file descriptor might actually receive events. |
1033 | events for them, only one file descriptor might actually receive events. |
1040 | |
1034 | |
1041 | There is no workaround possible except not registering events |
1035 | There is no workaround possible except not registering events |
1042 | for potentially C<dup ()>'ed file descriptors, or to resort to |
1036 | for potentially C<dup ()>'ed file descriptors, or to resort to |
1043 | C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>. |
1037 | C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>. |
1044 | |
1038 | |
… | |
… | |
1496 | semantics of C<ev_stat> watchers, which means that libev sometimes needs |
1490 | semantics of C<ev_stat> watchers, which means that libev sometimes needs |
1497 | to fall back to regular polling again even with inotify, but changes are |
1491 | to fall back to regular polling again even with inotify, but changes are |
1498 | usually detected immediately, and if the file exists there will be no |
1492 | usually detected immediately, and if the file exists there will be no |
1499 | polling. |
1493 | polling. |
1500 | |
1494 | |
|
|
1495 | =head3 Inotify |
|
|
1496 | |
|
|
1497 | When C<inotify (7)> support has been compiled into libev (generally only |
|
|
1498 | available on Linux) and present at runtime, it will be used to speed up |
|
|
1499 | change detection where possible. The inotify descriptor will be created lazily |
|
|
1500 | when the first C<ev_stat> watcher is being started. |
|
|
1501 | |
|
|
1502 | Inotify presense does not change the semantics of C<ev_stat> watchers |
|
|
1503 | except that changes might be detected earlier, and in some cases, to avoid |
|
|
1504 | making regular C<stat> calls. Even in the presense of inotify support |
|
|
1505 | there are many cases where libev has to resort to regular C<stat> polling. |
|
|
1506 | |
|
|
1507 | (There is no support for kqueue, as apparently it cannot be used to |
|
|
1508 | implement this functionality, due to the requirement of having a file |
|
|
1509 | descriptor open on the object at all times). |
|
|
1510 | |
|
|
1511 | =head3 The special problem of stat time resolution |
|
|
1512 | |
|
|
1513 | The C<stat ()> syscall only supports full-second resolution portably, and |
|
|
1514 | even on systems where the resolution is higher, many filesystems still |
|
|
1515 | only support whole seconds. |
|
|
1516 | |
|
|
1517 | That means that, if the time is the only thing that changes, you might |
|
|
1518 | miss updates: on the first update, C<ev_stat> detects a change and calls |
|
|
1519 | your callback, which does something. When there is another update within |
|
|
1520 | the same second, C<ev_stat> will be unable to detect it. |
|
|
1521 | |
|
|
1522 | The solution to this is to delay acting on a change for a second (or till |
|
|
1523 | the next second boundary), using a roughly one-second delay C<ev_timer> |
|
|
1524 | (C<ev_timer_set (w, 0., 1.01); ev_timer_again (loop, w)>). The C<.01> |
|
|
1525 | is added to work around small timing inconsistencies of some operating |
|
|
1526 | systems. |
|
|
1527 | |
1501 | =head3 Watcher-Specific Functions and Data Members |
1528 | =head3 Watcher-Specific Functions and Data Members |
1502 | |
1529 | |
1503 | =over 4 |
1530 | =over 4 |
1504 | |
1531 | |
1505 | =item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) |
1532 | =item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval) |
… | |
… | |
1542 | =item const char *path [read-only] |
1569 | =item const char *path [read-only] |
1543 | |
1570 | |
1544 | The filesystem path that is being watched. |
1571 | The filesystem path that is being watched. |
1545 | |
1572 | |
1546 | =back |
1573 | =back |
|
|
1574 | |
|
|
1575 | =head3 Examples |
1547 | |
1576 | |
1548 | Example: Watch C</etc/passwd> for attribute changes. |
1577 | Example: Watch C</etc/passwd> for attribute changes. |
1549 | |
1578 | |
1550 | static void |
1579 | static void |
1551 | passwd_cb (struct ev_loop *loop, ev_stat *w, int revents) |
1580 | passwd_cb (struct ev_loop *loop, ev_stat *w, int revents) |
… | |
… | |
1564 | } |
1593 | } |
1565 | |
1594 | |
1566 | ... |
1595 | ... |
1567 | ev_stat passwd; |
1596 | ev_stat passwd; |
1568 | |
1597 | |
1569 | ev_stat_init (&passwd, passwd_cb, "/etc/passwd"); |
1598 | ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.); |
1570 | ev_stat_start (loop, &passwd); |
1599 | ev_stat_start (loop, &passwd); |
|
|
1600 | |
|
|
1601 | Example: Like above, but additionally use a one-second delay so we do not |
|
|
1602 | miss updates (however, frequent updates will delay processing, too, so |
|
|
1603 | one might do the work both on C<ev_stat> callback invocation I<and> on |
|
|
1604 | C<ev_timer> callback invocation). |
|
|
1605 | |
|
|
1606 | static ev_stat passwd; |
|
|
1607 | static ev_timer timer; |
|
|
1608 | |
|
|
1609 | static void |
|
|
1610 | timer_cb (EV_P_ ev_timer *w, int revents) |
|
|
1611 | { |
|
|
1612 | ev_timer_stop (EV_A_ w); |
|
|
1613 | |
|
|
1614 | /* now it's one second after the most recent passwd change */ |
|
|
1615 | } |
|
|
1616 | |
|
|
1617 | static void |
|
|
1618 | stat_cb (EV_P_ ev_stat *w, int revents) |
|
|
1619 | { |
|
|
1620 | /* reset the one-second timer */ |
|
|
1621 | ev_timer_again (EV_A_ &timer); |
|
|
1622 | } |
|
|
1623 | |
|
|
1624 | ... |
|
|
1625 | ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.); |
|
|
1626 | ev_stat_start (loop, &passwd); |
|
|
1627 | ev_timer_init (&timer, timer_cb, 0., 1.01); |
1571 | |
1628 | |
1572 | |
1629 | |
1573 | =head2 C<ev_idle> - when you've got nothing better to do... |
1630 | =head2 C<ev_idle> - when you've got nothing better to do... |
1574 | |
1631 | |
1575 | Idle watchers trigger events when no other events of the same or higher |
1632 | Idle watchers trigger events when no other events of the same or higher |
… | |
… | |
2526 | than enough. If you need to manage thousands of children you might want to |
2583 | than enough. If you need to manage thousands of children you might want to |
2527 | increase this value (I<must> be a power of two). |
2584 | increase this value (I<must> be a power of two). |
2528 | |
2585 | |
2529 | =item EV_INOTIFY_HASHSIZE |
2586 | =item EV_INOTIFY_HASHSIZE |
2530 | |
2587 | |
2531 | C<ev_staz> watchers use a small hash table to distribute workload by |
2588 | C<ev_stat> watchers use a small hash table to distribute workload by |
2532 | inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), |
2589 | inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), |
2533 | usually more than enough. If you need to manage thousands of C<ev_stat> |
2590 | usually more than enough. If you need to manage thousands of C<ev_stat> |
2534 | watchers you might want to increase this value (I<must> be a power of |
2591 | watchers you might want to increase this value (I<must> be a power of |
2535 | two). |
2592 | two). |
2536 | |
2593 | |
… | |
… | |
2632 | |
2689 | |
2633 | =item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) |
2690 | =item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) |
2634 | |
2691 | |
2635 | This means that, when you have a watcher that triggers in one hour and |
2692 | This means that, when you have a watcher that triggers in one hour and |
2636 | there are 100 watchers that would trigger before that then inserting will |
2693 | there are 100 watchers that would trigger before that then inserting will |
2637 | have to skip those 100 watchers. |
2694 | have to skip roughly seven (C<ld 100>) of these watchers. |
2638 | |
2695 | |
2639 | =item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers) |
2696 | =item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers) |
2640 | |
2697 | |
2641 | That means that for changing a timer costs less than removing/adding them |
2698 | That means that changing a timer costs less than removing/adding them |
2642 | as only the relative motion in the event queue has to be paid for. |
2699 | as only the relative motion in the event queue has to be paid for. |
2643 | |
2700 | |
2644 | =item Starting io/check/prepare/idle/signal/child watchers: O(1) |
2701 | =item Starting io/check/prepare/idle/signal/child watchers: O(1) |
2645 | |
2702 | |
2646 | These just add the watcher into an array or at the head of a list. |
2703 | These just add the watcher into an array or at the head of a list. |
|
|
2704 | |
2647 | =item Stopping check/prepare/idle watchers: O(1) |
2705 | =item Stopping check/prepare/idle watchers: O(1) |
2648 | |
2706 | |
2649 | =item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) |
2707 | =item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) |
2650 | |
2708 | |
2651 | These watchers are stored in lists then need to be walked to find the |
2709 | These watchers are stored in lists then need to be walked to find the |
2652 | correct watcher to remove. The lists are usually short (you don't usually |
2710 | correct watcher to remove. The lists are usually short (you don't usually |
2653 | have many watchers waiting for the same fd or signal). |
2711 | have many watchers waiting for the same fd or signal). |
2654 | |
2712 | |
2655 | =item Finding the next timer per loop iteration: O(1) |
2713 | =item Finding the next timer in each loop iteration: O(1) |
|
|
2714 | |
|
|
2715 | By virtue of using a binary heap, the next timer is always found at the |
|
|
2716 | beginning of the storage array. |
2656 | |
2717 | |
2657 | =item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) |
2718 | =item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) |
2658 | |
2719 | |
2659 | A change means an I/O watcher gets started or stopped, which requires |
2720 | A change means an I/O watcher gets started or stopped, which requires |
2660 | libev to recalculate its status (and possibly tell the kernel). |
2721 | libev to recalculate its status (and possibly tell the kernel, depending |
|
|
2722 | on backend and wether C<ev_io_set> was used). |
2661 | |
2723 | |
2662 | =item Activating one watcher: O(1) |
2724 | =item Activating one watcher (putting it into the pending state): O(1) |
2663 | |
2725 | |
2664 | =item Priority handling: O(number_of_priorities) |
2726 | =item Priority handling: O(number_of_priorities) |
2665 | |
2727 | |
2666 | Priorities are implemented by allocating some space for each |
2728 | Priorities are implemented by allocating some space for each |
2667 | priority. When doing priority-based operations, libev usually has to |
2729 | priority. When doing priority-based operations, libev usually has to |
2668 | linearly search all the priorities. |
2730 | linearly search all the priorities, but starting/stopping and activating |
|
|
2731 | watchers becomes O(1) w.r.t. prioritiy handling. |
2669 | |
2732 | |
2670 | =back |
2733 | =back |
2671 | |
2734 | |
2672 | |
2735 | |
2673 | =head1 AUTHOR |
2736 | =head1 AUTHOR |