view release on metacpan or  search on metacpan

OpenCL.pm  view on Meta::CPAN

=head3 Don't use callbacks.

When your program never uses any callbacks, then there will never be any
notifications you need to take care of, and therefore no need to worry
about all this.

You can achieve a great deal by explicitly waiting for events, or using
barriers and flush calls. In many programs, there is no need at all to
tinker with asynchronous events.

=head3 Use AnyEvent

This module automatically registers a watcher that invokes all outstanding
event callbacks when AnyEvent is initialised (and block asynchronous
interruptions). Using this mode of operations is the safest and most
recommended one.

To use this, simply use AnyEvent and this module normally, make sure you
have an event loop running:

   use Gtk2 -init;
   use AnyEvent;

   # initialise AnyEvent, by creating a watcher, or:
   AnyEvent::detect;

   my $e = $queue->marker;
   $e->cb (sub {
      warn "opencl is finished\n";
   })

   main Gtk2;

Note that this module will not initialise AnyEvent for you. Before
AnyEvent is initialised, the module will asynchronously interrupt perl
instead. To avoid any surprises, it's best to explicitly initialise
AnyEvent.

You can temporarily enable asynchronous interruptions (see next paragraph)
by calling C<$OpenCL::INTERRUPT->unblock> and disable them again by
calling C<$OpenCL::INTERRUPT->block>.

=head3 Let yourself be interrupted at any time

This mode is the default unless AnyEvent is loaded and initialised. In
this mode, OpenCL asynchronously interrupts a running perl program. The
emphasis is on both I<asynchronously> and I<running> here.

Asynchronously means that perl might execute your callbacks at any
time. For example, in the following code (I<THAT YOU SHOULD NOT COPY>),
the C<until> loop following the marker call will be interrupted by the
callback:

   my $e = $queue->marker;
   my $flag;
   $e->cb (sub { $flag = 1 });
   1 until $flag;
   # $flag is now 1

The reason why you shouldn't blindly copy the above code is that
busy waiting is a really really bad thing, and really really bad for
performance.

While at first this asynchronous business might look exciting, it can be
really hard, because you need to be prepared for the callback code to be
executed at any time, which limits the amount of things the callback code
can do safely.

This can be mitigated somewhat by using C<<
$OpenCL::INTERRUPT->scope_block >> (see the L<Async::Interrupt>
documentation for details).

The other problem is that your program must be actively I<running> to be
interrupted. When you calculate stuff, your program is running.  When you
hang in some C functions or other block execution (by calling C<sleep>,
C<select>, running an event loop and so on), your program is waiting, not
running.

One way around that would be to attach a read watcher to your event loop,
listening for events on C<< $OpenCL::INTERRUPT->pipe_fileno >>, using a
dummy callback (C<sub { }>) to temporarily execute some perl code.

That is then awfully close to using the built-in AnyEvent support above,
though, so consider that one instead.

=head3 Be creative

OpenCL exports the L<Async::Interrupt> object it uses in the global
variable C<$OpenCL::INTERRUPT>. You can configure it in any way you like.

So if you want to feel like a real pro, err, wait, if you feel no risk
menas no fun, you can experiment by implementing your own mode of
operations.

=cut

package OpenCL;

use common::sense;
use Carp ();
use Async::Interrupt ();

our $POLL_FUNC; # set by XS

BEGIN {
   our $VERSION = '1.01';

   require XSLoader;
   XSLoader::load (__PACKAGE__, $VERSION);

   @OpenCL::Platform::ISA      =
   @OpenCL::Device::ISA        =
   @OpenCL::Context::ISA       =
   @OpenCL::Queue::ISA         =
   @OpenCL::Memory::ISA        =
   @OpenCL::Sampler::ISA       =
   @OpenCL::Program::ISA       =
   @OpenCL::Kernel::ISA        =
   @OpenCL::Event::ISA         = OpenCL::Object::;

   @OpenCL::SubDevice::ISA     = OpenCL::Device::;