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

Comparing libev/ev.3 (file contents):
Revision 1.16 by root, Sat Nov 24 10:19:14 2007 UTC vs.
Revision 1.17 by root, Sat Nov 24 16:31:45 2007 UTC

… …
717Libev will usually signal a few \*(L"dummy\*(R" events together with an error, 717Libev will usually signal a few \*(L"dummy\*(R" events together with an error,
718for example it might indicate that a fd is readable or writable, and if 718for example it might indicate that a fd is readable or writable, and if
719your callbacks is well-written it can just attempt the operation and cope 719your callbacks is well-written it can just attempt the operation and cope
720with the error from \fIread()\fR or \fIwrite()\fR. This will not work in multithreaded 720with the error from \fIread()\fR or \fIwrite()\fR. This will not work in multithreaded
721programs, though, so beware. 721programs, though, so beware.
722.Sh "\s-1SUMMARY\s0 \s-1OF\s0 \s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0" 722.Sh "\s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0"
723.IX Subsection "SUMMARY OF GENERIC WATCHER FUNCTIONS" 723.IX Subsection "GENERIC WATCHER FUNCTIONS"
724In the following description, \f(CW\*(C`TYPE\*(C'\fR stands for the watcher type, 724In the following description, \f(CW\*(C`TYPE\*(C'\fR stands for the watcher type,
725e.g. \f(CW\*(C`timer\*(C'\fR for \f(CW\*(C`ev_timer\*(C'\fR watchers and \f(CW\*(C`io\*(C'\fR for \f(CW\*(C`ev_io\*(C'\fR watchers. 725e.g. \f(CW\*(C`timer\*(C'\fR for \f(CW\*(C`ev_timer\*(C'\fR watchers and \f(CW\*(C`io\*(C'\fR for \f(CW\*(C`ev_io\*(C'\fR watchers.
726.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4 726.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
727.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4 727.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4
728.IX Item "ev_init (ev_TYPE *watcher, callback)" 728.IX Item "ev_init (ev_TYPE *watcher, callback)"
… …
734which rolls both calls into one. 734which rolls both calls into one.
735.Sp 735.Sp
736You can reinitialise a watcher at any time as long as it has been stopped 736You can reinitialise a watcher at any time as long as it has been stopped
737(or never started) and there are no pending events outstanding. 737(or never started) and there are no pending events outstanding.
738.Sp 738.Sp
739The callbakc is always of type \f(CW\*(C`void (*)(ev_loop *loop, ev_TYPE *watcher, 739The callback is always of type \f(CW\*(C`void (*)(ev_loop *loop, ev_TYPE *watcher,
740int revents)\*(C'\fR. 740int revents)\*(C'\fR.
741.ie n .IP """ev_TYPE_set"" (ev_TYPE *, [args])" 4 741.ie n .IP """ev_TYPE_set"" (ev_TYPE *, [args])" 4
742.el .IP "\f(CWev_TYPE_set\fR (ev_TYPE *, [args])" 4 742.el .IP "\f(CWev_TYPE_set\fR (ev_TYPE *, [args])" 4
743.IX Item "ev_TYPE_set (ev_TYPE *, [args])" 743.IX Item "ev_TYPE_set (ev_TYPE *, [args])"
744This macro initialises the type-specific parts of a watcher. You need to 744This macro initialises the type-specific parts of a watcher. You need to
… …
822have been omitted.... 822have been omitted....
823.SH "WATCHER TYPES" 823.SH "WATCHER TYPES"
824.IX Header "WATCHER TYPES" 824.IX Header "WATCHER TYPES"
825This section describes each watcher in detail, but will not repeat 825This section describes each watcher in detail, but will not repeat
826information given in the last section. 826information given in the last section.
827.ie n .Sh """ev_io"" \- is this file descriptor readable or writable" 827.ie n .Sh """ev_io"" \- is this file descriptor readable or writable?"
828.el .Sh "\f(CWev_io\fP \- is this file descriptor readable or writable" 828.el .Sh "\f(CWev_io\fP \- is this file descriptor readable or writable?"
829.IX Subsection "ev_io - is this file descriptor readable or writable" 829.IX Subsection "ev_io - is this file descriptor readable or writable?"
830I/O watchers check whether a file descriptor is readable or writable 830I/O watchers check whether a file descriptor is readable or writable
831in each iteration of the event loop (This behaviour is called 831in each iteration of the event loop, or, more precisely, when reading
832level-triggering because you keep receiving events as long as the 832would not block the process and writing would at least be able to write
833condition persists. Remember you can stop the watcher if you don't want to 833some data. This behaviour is called level-triggering because you keep
834act on the event and neither want to receive future events). 834receiving events as long as the condition persists. Remember you can stop
835the watcher if you don't want to act on the event and neither want to
836receive future events.
835.PP 837.PP
836In general you can register as many read and/or write event watchers per 838In general you can register as many read and/or write event watchers per
837fd as you want (as long as you don't confuse yourself). Setting all file 839fd as you want (as long as you don't confuse yourself). Setting all file
838descriptors to non-blocking mode is also usually a good idea (but not 840descriptors to non-blocking mode is also usually a good idea (but not
839required if you know what you are doing). 841required if you know what you are doing).
840.PP 842.PP
841You have to be careful with dup'ed file descriptors, though. Some backends 843You have to be careful with dup'ed file descriptors, though. Some backends
842(the linux epoll backend is a notable example) cannot handle dup'ed file 844(the linux epoll backend is a notable example) cannot handle dup'ed file
843descriptors correctly if you register interest in two or more fds pointing 845descriptors correctly if you register interest in two or more fds pointing
844to the same underlying file/socket etc. description (that is, they share 846to the same underlying file/socket/etc. description (that is, they share
845the same underlying \*(L"file open\*(R"). 847the same underlying \*(L"file open\*(R").
846.PP 848.PP
847If you must do this, then force the use of a known-to-be-good backend 849If you must do this, then force the use of a known-to-be-good backend
848(at the time of this writing, this includes only \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR and 850(at the time of this writing, this includes only \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR and
849\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR). 851\&\f(CW\*(C`EVBACKEND_POLL\*(C'\fR).
852.PP
853Another thing you have to watch out for is that it is quite easy to
854receive \*(L"spurious\*(R" readyness notifications, that is your callback might
855be called with \f(CW\*(C`EV_READ\*(C'\fR but a subsequent \f(CW\*(C`read\*(C'\fR(2) will actually block
856because there is no data. Not only are some backends known to create a
857lot of those (for example solaris ports), it is very easy to get into
858this situation even with a relatively standard program structure. Thus
859it is best to always use non-blocking I/O: An extra \f(CW\*(C`read\*(C'\fR(2) returning
860\&\f(CW\*(C`EAGAIN\*(C'\fR is far preferable to a program hanging until some data arrives.
861.PP
862If you cannot run the fd in non-blocking mode (for example you should not
863play around with an Xlib connection), then you have to seperately re-test
864wether a file descriptor is really ready with a known-to-be good interface
865such as poll (fortunately in our Xlib example, Xlib already does this on
866its own, so its quite safe to use).
850.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4 867.IP "ev_io_init (ev_io *, callback, int fd, int events)" 4
851.IX Item "ev_io_init (ev_io *, callback, int fd, int events)" 868.IX Item "ev_io_init (ev_io *, callback, int fd, int events)"
852.PD 0 869.PD 0
853.IP "ev_io_set (ev_io *, int fd, int events)" 4 870.IP "ev_io_set (ev_io *, int fd, int events)" 4
854.IX Item "ev_io_set (ev_io *, int fd, int events)" 871.IX Item "ev_io_set (ev_io *, int fd, int events)"
855.PD 872.PD
856Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The fd is the file descriptor to rceeive 873Configures an \f(CW\*(C`ev_io\*(C'\fR watcher. The \f(CW\*(C`fd\*(C'\fR is the file descriptor to
857events for and events is either \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or \f(CW\*(C`EV_READ | 874rceeive events for and events is either \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or
858EV_WRITE\*(C'\fR to receive the given events. 875\&\f(CW\*(C`EV_READ | EV_WRITE\*(C'\fR to receive the given events.
859.Sp
860Please note that most of the more scalable backend mechanisms (for example
861epoll and solaris ports) can result in spurious readyness notifications
862for file descriptors, so you practically need to use non-blocking I/O (and
863treat callback invocation as hint only), or retest separately with a safe
864interface before doing I/O (XLib can do this), or force the use of either
865\&\f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR, which don't suffer from this
866problem. Also note that it is quite easy to have your callback invoked
867when the readyness condition is no longer valid even when employing
868typical ways of handling events, so its a good idea to use non-blocking
869I/O unconditionally.
870.PP 876.PP
871Example: call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well 877Example: call \f(CW\*(C`stdin_readable_cb\*(C'\fR when \s-1STDIN_FILENO\s0 has become, well
872readable, but only once. Since it is likely line\-buffered, you could 878readable, but only once. Since it is likely line\-buffered, you could
873attempt to read a whole line in the callback: 879attempt to read a whole line in the callback:
874.PP 880.PP
… …
887\& struct ev_io stdin_readable; 893\& struct ev_io stdin_readable;
888\& ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ); 894\& ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
889\& ev_io_start (loop, &stdin_readable); 895\& ev_io_start (loop, &stdin_readable);
890\& ev_loop (loop, 0); 896\& ev_loop (loop, 0);
891.Ve 897.Ve
892.ie n .Sh """ev_timer"" \- relative and optionally recurring timeouts" 898.ie n .Sh """ev_timer"" \- relative and optionally repeating timeouts"
893.el .Sh "\f(CWev_timer\fP \- relative and optionally recurring timeouts" 899.el .Sh "\f(CWev_timer\fP \- relative and optionally repeating timeouts"
894.IX Subsection "ev_timer - relative and optionally recurring timeouts" 900.IX Subsection "ev_timer - relative and optionally repeating timeouts"
895Timer watchers are simple relative timers that generate an event after a 901Timer watchers are simple relative timers that generate an event after a
896given time, and optionally repeating in regular intervals after that. 902given time, and optionally repeating in regular intervals after that.
897.PP 903.PP
898The timers are based on real time, that is, if you register an event that 904The timers are based on real time, that is, if you register an event that
899times out after an hour and you reset your system clock to last years 905times out after an hour and you reset your system clock to last years
… …
986.Vb 3 992.Vb 3
987\& // and in some piece of code that gets executed on any "activity": 993\& // and in some piece of code that gets executed on any "activity":
988\& // reset the timeout to start ticking again at 10 seconds 994\& // reset the timeout to start ticking again at 10 seconds
989\& ev_timer_again (&mytimer); 995\& ev_timer_again (&mytimer);
990.Ve 996.Ve
991.ie n .Sh """ev_periodic"" \- to cron or not to cron" 997.ie n .Sh """ev_periodic"" \- to cron or not to cron?"
992.el .Sh "\f(CWev_periodic\fP \- to cron or not to cron" 998.el .Sh "\f(CWev_periodic\fP \- to cron or not to cron?"
993.IX Subsection "ev_periodic - to cron or not to cron" 999.IX Subsection "ev_periodic - to cron or not to cron?"
994Periodic watchers are also timers of a kind, but they are very versatile 1000Periodic watchers are also timers of a kind, but they are very versatile
995(and unfortunately a bit complex). 1001(and unfortunately a bit complex).
996.PP 1002.PP
997Unlike \f(CW\*(C`ev_timer\*(C'\fR's, they are not based on real time (or relative time) 1003Unlike \f(CW\*(C`ev_timer\*(C'\fR's, they are not based on real time (or relative time)
998but on wallclock time (absolute time). You can tell a periodic watcher 1004but on wallclock time (absolute time). You can tell a periodic watcher
… …
1132\& struct ev_periodic hourly_tick; 1138\& struct ev_periodic hourly_tick;
1133\& ev_periodic_init (&hourly_tick, clock_cb, 1139\& ev_periodic_init (&hourly_tick, clock_cb,
1134\& fmod (ev_now (loop), 3600.), 3600., 0); 1140\& fmod (ev_now (loop), 3600.), 3600., 0);
1135\& ev_periodic_start (loop, &hourly_tick); 1141\& ev_periodic_start (loop, &hourly_tick);
1136.Ve 1142.Ve
1137.ie n .Sh """ev_signal"" \- signal me when a signal gets signalled" 1143.ie n .Sh """ev_signal"" \- signal me when a signal gets signalled!"
1138.el .Sh "\f(CWev_signal\fP \- signal me when a signal gets signalled" 1144.el .Sh "\f(CWev_signal\fP \- signal me when a signal gets signalled!"
1139.IX Subsection "ev_signal - signal me when a signal gets signalled" 1145.IX Subsection "ev_signal - signal me when a signal gets signalled!"
1140Signal watchers will trigger an event when the process receives a specific 1146Signal watchers will trigger an event when the process receives a specific
1141signal one or more times. Even though signals are very asynchronous, libev 1147signal one or more times. Even though signals are very asynchronous, libev
1142will try it's best to deliver signals synchronously, i.e. as part of the 1148will try it's best to deliver signals synchronously, i.e. as part of the
1143normal event processing, like any other event. 1149normal event processing, like any other event.
1144.PP 1150.PP
… …
1154.IP "ev_signal_set (ev_signal *, int signum)" 4 1160.IP "ev_signal_set (ev_signal *, int signum)" 4
1155.IX Item "ev_signal_set (ev_signal *, int signum)" 1161.IX Item "ev_signal_set (ev_signal *, int signum)"
1156.PD 1162.PD
1157Configures the watcher to trigger on the given signal number (usually one 1163Configures the watcher to trigger on the given signal number (usually one
1158of the \f(CW\*(C`SIGxxx\*(C'\fR constants). 1164of the \f(CW\*(C`SIGxxx\*(C'\fR constants).
1159.ie n .Sh """ev_child"" \- wait for pid status changes" 1165.ie n .Sh """ev_child"" \- watch out for process status changes"
1160.el .Sh "\f(CWev_child\fP \- wait for pid status changes" 1166.el .Sh "\f(CWev_child\fP \- watch out for process status changes"
1161.IX Subsection "ev_child - wait for pid status changes" 1167.IX Subsection "ev_child - watch out for process status changes"
1162Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to 1168Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to
1163some child status changes (most typically when a child of yours dies). 1169some child status changes (most typically when a child of yours dies).
1164.IP "ev_child_init (ev_child *, callback, int pid)" 4 1170.IP "ev_child_init (ev_child *, callback, int pid)" 4
1165.IX Item "ev_child_init (ev_child *, callback, int pid)" 1171.IX Item "ev_child_init (ev_child *, callback, int pid)"
1166.PD 0 1172.PD 0
… …
1187.Vb 3 1193.Vb 3
1188\& struct ev_signal signal_watcher; 1194\& struct ev_signal signal_watcher;
1189\& ev_signal_init (&signal_watcher, sigint_cb, SIGINT); 1195\& ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1190\& ev_signal_start (loop, &sigint_cb); 1196\& ev_signal_start (loop, &sigint_cb);
1191.Ve 1197.Ve
1192.ie n .Sh """ev_idle"" \- when you've got nothing better to do" 1198.ie n .Sh """ev_idle"" \- when you've got nothing better to do..."
1193.el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do" 1199.el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do..."
1194.IX Subsection "ev_idle - when you've got nothing better to do" 1200.IX Subsection "ev_idle - when you've got nothing better to do..."
1195Idle watchers trigger events when there are no other events are pending 1201Idle watchers trigger events when there are no other events are pending
1196(prepare, check and other idle watchers do not count). That is, as long 1202(prepare, check and other idle watchers do not count). That is, as long
1197as your process is busy handling sockets or timeouts (or even signals, 1203as your process is busy handling sockets or timeouts (or even signals,
1198imagine) it will not be triggered. But when your process is idle all idle 1204imagine) it will not be triggered. But when your process is idle all idle
1199watchers are being called again and again, once per event loop iteration \- 1205watchers are being called again and again, once per event loop iteration \-
… …
1229.Vb 3 1235.Vb 3
1230\& struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle)); 1236\& struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
1231\& ev_idle_init (idle_watcher, idle_cb); 1237\& ev_idle_init (idle_watcher, idle_cb);
1232\& ev_idle_start (loop, idle_cb); 1238\& ev_idle_start (loop, idle_cb);
1233.Ve 1239.Ve
1234.ie n .Sh """ev_prepare""\fP and \f(CW""ev_check"" \- customise your event loop" 1240.ie n .Sh """ev_prepare""\fP and \f(CW""ev_check"" \- customise your event loop!"
1235.el .Sh "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop" 1241.el .Sh "\f(CWev_prepare\fP and \f(CWev_check\fP \- customise your event loop!"
1236.IX Subsection "ev_prepare and ev_check - customise your event loop" 1242.IX Subsection "ev_prepare and ev_check - customise your event loop!"
1237Prepare and check watchers are usually (but not always) used in tandem: 1243Prepare and check watchers are usually (but not always) used in tandem:
1238prepare watchers get invoked before the process blocks and check watchers 1244prepare watchers get invoked before the process blocks and check watchers
1239afterwards. 1245afterwards.
1240.PP 1246.PP
1241Their main purpose is to integrate other event mechanisms into libev and 1247Their main purpose is to integrate other event mechanisms into libev and
… …
1269Initialises and configures the prepare or check watcher \- they have no 1275Initialises and configures the prepare or check watcher \- they have no
1270parameters of any kind. There are \f(CW\*(C`ev_prepare_set\*(C'\fR and \f(CW\*(C`ev_check_set\*(C'\fR 1276parameters of any kind. There are \f(CW\*(C`ev_prepare_set\*(C'\fR and \f(CW\*(C`ev_check_set\*(C'\fR
1271macros, but using them is utterly, utterly and completely pointless. 1277macros, but using them is utterly, utterly and completely pointless.
1272.PP 1278.PP
1273Example: *TODO*. 1279Example: *TODO*.
1274.ie n .Sh """ev_embed"" \- when one backend isn't enough" 1280.ie n .Sh """ev_embed"" \- when one backend isn't enough..."
1275.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough" 1281.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..."
1276.IX Subsection "ev_embed - when one backend isn't enough" 1282.IX Subsection "ev_embed - when one backend isn't enough..."
1277This is a rather advanced watcher type that lets you embed one event loop 1283This is a rather advanced watcher type that lets you embed one event loop
1278into another (currently only \f(CW\*(C`ev_io\*(C'\fR events are supported in the embedded 1284into another (currently only \f(CW\*(C`ev_io\*(C'\fR events are supported in the embedded
1279loop, other types of watchers might be handled in a delayed or incorrect 1285loop, other types of watchers might be handled in a delayed or incorrect
1280fashion and must not be used). 1286fashion and must not be used).
1281.PP 1287.PP

Diff Legend

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