NAME
Net::Curl::Promiser - Asynchronous libcurl, the easy way!
DESCRIPTION
Net::Curl::Multi is powerful but tricky to use: polling, callbacks, timers, etc. This module does all of that for you and puts a Promise interface on top of it, so asynchronous I/O becomes almost as simple as synchronous I/O.
Net::Curl::Promiser itself is a base class; you’ll need to use a subclass that works with your chosen event interface.
This distribution provides the following usable subclasses:
Net::Curl::Promiser::Select (for manually-written
select()loops)
If the event interface you want to use isn’t compatible with one of the above, you’ll need to create your own Net::Curl::Promiser subclass. This is undocumented but pretty simple; have a look at the ones above as well as another based on Linux’s epoll(7) in the distribution’s /examples.
MEMORY LEAK DETECTION
This module will, by default, warn() if its objects are DESTROY()ed during Perl’s global destruction phase. To suppress this behavior, set $Net::Curl::Promiser::IGNORE_MEMORY_LEAKS to a truthy value.
PROMISE IMPLEMENTATION
This class’s default Promise implementation is Promise::ES6. You can use a different one by overriding the PROMISE_CLASS() method in a subclass, as long as the substitute class’s new() method works the same way as Promise::ES6’s (which itself follows the ECMAScript standard).
(NB: Net::Curl::Promiser::Mojo uses Mojo::Promise instead of Promise::ES6.)
Experimental Promise::XS support
Try out experimental Promise::XS support by running with NET_CURL_PROMISER_PROMISE_ENGINE=Promise::XS in your environment. This will override PROMISE_CLASS().
DESIGN NOTES
Internally each instance of this class uses an instance of Net::Curl::Multi and an instance of Net::Curl::Promiser::Backend. (The latter, in turn, is subclassed to provide logic specific to each event interface.) These are kept separate to avoid circular references.
GENERAL-USE METHODS
The following are of interest to any code that uses this module:
CLASS->new(@ARGS)
Instantiates this class, including creation of an underlying Net::Curl::Multi object.
promise($EASY) = OBJ->add_handle( $EASY )
A passthrough to the underlying Net::Curl::Multi object’s method of the same name, but the return is given as a Promise object.
That promise resolves with the passed-in $EASY object. It rejects with either the error given to fail_handle() or the error that Net::Curl::Multi object’s info_read() returns.
IMPORTANT: As with libcurl itself, HTTP-level failures (e.g., 4xx and 5xx responses) are NOT considered failures at this level.
$obj = OBJ->cancel_handle( $EASY )
Prematurely cancels $EASY. The associated promise will be abandoned in pending state, never to resolve nor reject.
Returns OBJ.
$obj = OBJ->fail_handle( $EASY, $REASON )
Like cancel_handle() but rejects $EASY’s associated promise with the given $REASON.
Returns OBJ.
$obj = OBJ->setopt( … )
A passthrough to the underlying Net::Curl::Multi object’s method of the same name. Returns OBJ to facilitate chaining.
This class requires control of certain Net::Curl::Multi options; if you attempt to set one of these here you’ll get an exception.
$obj = OBJ->handles( … )
A passthrough to the underlying Net::Curl::Multi object’s method of the same name.
EXAMPLES
See the distribution’s /examples directory.
SEE ALSO
Try Net::Curl::Easier for a more polished variant of Net::Curl::Easy.
Net::Curl::Simple implements a similar idea to this module but doesn’t return promises. It has a more extensive interface that provides a more “perlish” experience than Net::Curl::Easy.
If you use AnyEvent, then AnyEvent::XSPromises with AnyEvent::YACurl may be a nicer fit for you.
REPOSITORY
https://github.com/FGasper/p5-Net-Curl-Promiser
LICENSE & COPYRIGHT
Copyright 2019-2020 Gasper Software Consulting.
This library is licensed under the same terms as Perl itself.