ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.232 by root, Thu Jul 9 01:08:22 2009 UTC vs.
Revision 1.233 by root, Thu Jul 9 01:22:50 2009 UTC

… …
809 809
810=back 810=back
811 811
812=head1 GLOBAL VARIABLES AND FUNCTIONS 812=head1 GLOBAL VARIABLES AND FUNCTIONS
813 813
814These are not normally required to use AnyEvent, but can be useful to
815write AnyEvent extension modules.
816
814=over 4 817=over 4
815 818
816=item $AnyEvent::MODEL 819=item $AnyEvent::MODEL
817 820
818Contains C<undef> until the first watcher is being created. Then it 821Contains C<undef> until the first watcher is being created, before the
822backend has been autodetected.
823
819contains the event model that is being used, which is the name of the 824Afterwards it contains the event model that is being used, which is the
820Perl class implementing the model. This class is usually one of the 825name of the Perl class implementing the model. This class is usually one
821C<AnyEvent::Impl:xxx> modules, but can be any other class in the case 826of the C<AnyEvent::Impl:xxx> modules, but can be any other class in the
822AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 827case AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode> it
828will be C<urxvt::anyevent>).
823 829
824=item AnyEvent::detect 830=item AnyEvent::detect
825 831
826Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 832Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
827if necessary. You should only call this function right before you would 833if necessary. You should only call this function right before you would
828have created an AnyEvent watcher anyway, that is, as late as possible at 834have created an AnyEvent watcher anyway, that is, as late as possible at
829runtime. 835runtime, and not e.g. while initialising of your module.
836
837If you need to do some initialisation before AnyEvent watchers are
838created, use C<post_detect>.
830 839
831=item $guard = AnyEvent::post_detect { BLOCK } 840=item $guard = AnyEvent::post_detect { BLOCK }
832 841
833Arranges for the code block to be executed as soon as the event model is 842Arranges for the code block to be executed as soon as the event model is
834autodetected (or immediately if this has already happened). 843autodetected (or immediately if this has already happened).
844
845The block will be executed I<after> the actual backend has been detected
846(C<$AnyEvent::MODEL> is set), but I<before> any watchers have been
847created, so it is possible to e.g. patch C<@AnyEvent::ISA> or do
848other initialisations - see the sources of L<AnyEvent::Strict> or
849L<AnyEvent::AIO> to see how this is used.
850
851The most common usage is to create some global watchers, without forcing
852event module detection too early, for example, L<AnyEvent::AIO> creates
853and installs the global L<IO::AIO> watcher in a C<post_detect> block to
854avoid autodetecting the event module at load time.
835 855
836If called in scalar or list context, then it creates and returns an object 856If called in scalar or list context, then it creates and returns an object
837that automatically removes the callback again when it is destroyed. See 857that automatically removes the callback again when it is destroyed. See
838L<Coro::BDB> for a case where this is useful. 858L<Coro::BDB> for a case where this is useful.
839 859
… …
842If there are any code references in this array (you can C<push> to it 862If there are any code references in this array (you can C<push> to it
843before or after loading AnyEvent), then they will called directly after 863before or after loading AnyEvent), then they will called directly after
844the event loop has been chosen. 864the event loop has been chosen.
845 865
846You should check C<$AnyEvent::MODEL> before adding to this array, though: 866You should check C<$AnyEvent::MODEL> before adding to this array, though:
847if it contains a true value then the event loop has already been detected, 867if it is defined then the event loop has already been detected, and the
848and the array will be ignored. 868array will be ignored.
849 869
850Best use C<AnyEvent::post_detect { BLOCK }> instead. 870Best use C<AnyEvent::post_detect { BLOCK }> when your application allows
871it,as it takes care of these details.
872
873This variable is mainly useful for modules that can do something useful
874when AnyEvent is used and thus want to know when it is initialised, but do
875not need to even load it by default. This array provides the means to hook
876into AnyEvent passively, without loading it.
851 877
852=back 878=back
853 879
854=head1 WHAT TO DO IN A MODULE 880=head1 WHAT TO DO IN A MODULE
855 881

Diff Legend

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