view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    Since Async::Interrupt is a bit hard to understand, here are some case
    examples:

   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.

   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 "$OpenCL::INTERRUPT-"unblock> and disable them
    again by calling "$OpenCL::INTERRUPT-"block>.

   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 *asynchronously* and *running* here.

    Asynchronously means that perl might execute your callbacks at any time.
    For example, in the following code (*THAT YOU SHOULD NOT COPY*), the
    "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
    "$OpenCL::INTERRUPT->scope_block" (see the Async::Interrupt
    documentation for details).

    The other problem is that your program must be actively *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 "sleep",
    "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 "$OpenCL::INTERRUPT->pipe_fileno", using a
    dummy callback ("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.

   Be creative
    OpenCL exports the Async::Interrupt object it uses in the global
    variable $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.

  THE OpenCL PACKAGE
    $int = OpenCL::errno
        The last error returned by a function - it's only valid after an
        error occured and before calling another OpenCL function.

    $str = OpenCL::err2str [$errval]
        Converts an error value into a human readable string. If no error
        value is given, then the last error will be used (as returned by
        OpenCL::errno).

        The latest version of this module knows the error constants listed
        in <http://cvs.schmorp.de/OpenCL/errstr.h>.

    $str = OpenCL::enum2str $enum
        Converts most enum values (of parameter names, image format
        constants, object types, addressing and filter modes, command types
        etc.) into a human readable string. When confronted with some random
        integer it can be very helpful to pass it through this function to
        maybe get some readable string out of it.

        The latest version of this module knows the enumaration constants
        listed in <http://cvs.schmorp.de/OpenCL/enumstr.h>.

    @platforms = OpenCL::platforms
        Returns all available OpenCL::Platform objects.

        <http://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/clGetPlat