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

Comparing libev/ev.pod (file contents):
Revision 1.312 by root, Thu Oct 21 15:14:49 2010 UTC vs.
Revision 1.316 by root, Fri Oct 22 09:34:01 2010 UTC

… …
908 908
909=item ev_invoke_pending (loop) 909=item ev_invoke_pending (loop)
910 910
911This call will simply invoke all pending watchers while resetting their 911This call will simply invoke all pending watchers while resetting their
912pending state. Normally, C<ev_run> does this automatically when required, 912pending state. Normally, C<ev_run> does this automatically when required,
913but when overriding the invoke callback this call comes handy. 913but when overriding the invoke callback this call comes handy. This
914function can be invoked from a watcher - this can be useful for example
915when you want to do some lengthy calculation and want to pass further
916event handling to another thread (you still have to make sure only one
917thread executes within C<ev_invoke_pending> or C<ev_run> of course).
914 918
915=item int ev_pending_count (loop) 919=item int ev_pending_count (loop)
916 920
917Returns the number of pending watchers - zero indicates that no watchers 921Returns the number of pending watchers - zero indicates that no watchers
918are pending. 922are pending.
… …
4527=head3 C<kqueue> is buggy 4531=head3 C<kqueue> is buggy
4528 4532
4529The kqueue syscall is broken in all known versions - most versions support 4533The kqueue syscall is broken in all known versions - most versions support
4530only sockets, many support pipes. 4534only sockets, many support pipes.
4531 4535
4532Libev tries to work around this by not using C<kqueue> by default on 4536Libev tries to work around this by not using C<kqueue> by default on this
4533this rotten platform, but of course you can still ask for it when creating 4537rotten platform, but of course you can still ask for it when creating a
4534a loop. 4538loop - embedding a socket-only kqueue loop into a select-based one is
4539probably going to work well.
4535 4540
4536=head3 C<poll> is buggy 4541=head3 C<poll> is buggy
4537 4542
4538Instead of fixing C<kqueue>, Apple replaced their (working) C<poll> 4543Instead of fixing C<kqueue>, Apple replaced their (working) C<poll>
4539implementation by something calling C<kqueue> internally around the 10.5.6 4544implementation by something calling C<kqueue> internally around the 10.5.6
… …
4558 4563
4559=head3 C<errno> reentrancy 4564=head3 C<errno> reentrancy
4560 4565
4561The default compile environment on Solaris is unfortunately so 4566The default compile environment on Solaris is unfortunately so
4562thread-unsafe that you can't even use components/libraries compiled 4567thread-unsafe that you can't even use components/libraries compiled
4563without C<-D_REENTRANT> (as long as they use C<errno>), which, of course, 4568without C<-D_REENTRANT> in a threaded program, which, of course, isn't
4564isn't defined by default. 4569defined by default. A valid, if stupid, implementation choice.
4565 4570
4566If you want to use libev in threaded environments you have to make sure 4571If you want to use libev in threaded environments you have to make sure
4567it's compiled with C<_REENTRANT> defined. 4572it's compiled with C<_REENTRANT> defined.
4568 4573
4569=head3 Event port backend 4574=head3 Event port backend
4570 4575
4571The scalable event interface for Solaris is called "event ports". Unfortunately, 4576The scalable event interface for Solaris is called "event
4572this mechanism is very buggy. If you run into high CPU usage, your program 4577ports". Unfortunately, this mechanism is very buggy in all major
4578releases. If you run into high CPU usage, your program freezes or you get
4573freezes or you get a large number of spurious wakeups, make sure you have 4579a large number of spurious wakeups, make sure you have all the relevant
4574all the relevant and latest kernel patches applied. No, I don't know which 4580and latest kernel patches applied. No, I don't know which ones, but there
4575ones, but there are multiple ones. 4581are multiple ones to apply, and afterwards, event ports actually work
4582great.
4576 4583
4577If you can't get it to work, you can try running the program by setting 4584If you can't get it to work, you can try running the program by setting
4578the environment variable C<LIBEV_FLAGS=3> to only allow C<poll> and 4585the environment variable C<LIBEV_FLAGS=3> to only allow C<poll> and
4579C<select> backends. 4586C<select> backends.
4580 4587
4581=head2 AIX POLL BUG 4588=head2 AIX POLL BUG
4582 4589
4583AIX unfortunately has a broken C<poll.h> header. Libev works around 4590AIX unfortunately has a broken C<poll.h> header. Libev works around
4584this by trying to avoid the poll backend altogether (i.e. it's not even 4591this by trying to avoid the poll backend altogether (i.e. it's not even
4585compiled in), which normally isn't a big problem as C<select> works fine 4592compiled in), which normally isn't a big problem as C<select> works fine
4586with large bitsets, and AIX is dead anyway. 4593with large bitsets on AIX, and AIX is dead anyway.
4587 4594
4588=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS 4595=head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
4589 4596
4590=head3 General issues 4597=head3 General issues
4591 4598
… …
4868 4875
4869=over 4 4876=over 4
4870 4877
4871=item active 4878=item active
4872 4879
4873A watcher is active as long as it has been started (has been attached to 4880A watcher is active as long as it has been started and not yet stopped.
4874an event loop) but not yet stopped (disassociated from the event loop). 4881See L<WATCHER STATES> for details.
4875 4882
4876=item application 4883=item application
4877 4884
4878In this document, an application is whatever is using libev. 4885In this document, an application is whatever is using libev.
4886
4887=item backend
4888
4889The part of the code dealing with the operating system interfaces.
4879 4890
4880=item callback 4891=item callback
4881 4892
4882The address of a function that is called when some event has been 4893The address of a function that is called when some event has been
4883detected. Callbacks are being passed the event loop, the watcher that 4894detected. Callbacks are being passed the event loop, the watcher that
4884received the event, and the actual event bitset. 4895received the event, and the actual event bitset.
4885 4896
4886=item callback invocation 4897=item callback/watcher invocation
4887 4898
4888The act of calling the callback associated with a watcher. 4899The act of calling the callback associated with a watcher.
4889 4900
4890=item event 4901=item event
4891 4902
… …
4910The model used to describe how an event loop handles and processes 4921The model used to describe how an event loop handles and processes
4911watchers and events. 4922watchers and events.
4912 4923
4913=item pending 4924=item pending
4914 4925
4915A watcher is pending as soon as the corresponding event has been detected, 4926A watcher is pending as soon as the corresponding event has been
4916and stops being pending as soon as the watcher will be invoked or its 4927detected. See L<WATCHER STATES> for details.
4917pending status is explicitly cleared by the application.
4918
4919A watcher can be pending, but not active. Stopping a watcher also clears
4920its pending status.
4921 4928
4922=item real time 4929=item real time
4923 4930
4924The physical time that is observed. It is apparently strictly monotonic :) 4931The physical time that is observed. It is apparently strictly monotonic :)
4925 4932
… …
4932=item watcher 4939=item watcher
4933 4940
4934A data structure that describes interest in certain events. Watchers need 4941A data structure that describes interest in certain events. Watchers need
4935to be started (attached to an event loop) before they can receive events. 4942to be started (attached to an event loop) before they can receive events.
4936 4943
4937=item watcher invocation
4938
4939The act of calling the callback associated with a watcher.
4940
4941=back 4944=back
4942 4945
4943=head1 AUTHOR 4946=head1 AUTHOR
4944 4947
4945Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson. 4948Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.

Diff Legend

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