Net::Curl::Promiser - A Promise interface for Net::Curl::Multi
This module wraps Net::Curl::Multi to facilitate asynchronous HTTP requests with Promise objects.
Net::Curl::Promiser itself is a base class; you’ll need to provide an interface to whatever event loop you use. See "SUBCLASS INTERFACE" below.
This distribution provides the following as both demonstrations and portable implementations:
Net::Curl::Promiser::Select
Net::Curl::Promiser::IOAsync (for IO::Async)
Net::Curl::Promiser::Mojo (for Mojolicious)
Net::Curl::Promiser::AnyEvent (for AnyEvent)
(See the distribution’s /examples directory for one based on Linux’s epoll.)
epoll
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).
new()
Instantiates this class. This creates an underlying Net::Curl::Multi object and calls the subclass’s _INIT() method at the end, passing a reference to @ARGS.
_INIT()
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.
fail_handle()
info_read()
IMPORTANT: As with libcurl itself, HTTP-level failures (e.g., 4xx and 5xx responses) are NOT considered failures at this level.
Prematurely fails $EASY. The given $REASON will be the associated Promise object’s rejection value.
Returns the underlying Net::Curl::Multi object’s timeout() value, with a suitable (positive) default substituted if that value is less than 0.
timeout()
(NB: This value is in milliseconds.)
This may not suit your needs; if you wish/need, you can handle timeouts via the CURLMOPT_TIMERFUNCTION callback instead.
This should only be called (if it’s called at all) from event loop logic.
Tell the underlying Net::Curl::Multi object which socket events have happened.
If, in fact, no events have happened, then this calls socket_action(CURL_SOCKET_TIMEOUT) on the Net::Curl::Multi object (similar to time_out()).
socket_action(CURL_SOCKET_TIMEOUT)
time_out()
Finally, this reaps whatever pending HTTP responses may be ready and resolves or rejects the corresponding Promise objects.
This should only be called from event loop logic.
Returns OBJ.
Tell the underlying Net::Curl::Multi object that a timeout happened, and reap whatever pending HTTP responses may be ready.
Calls socket_action(CURL_SOCKET_TIMEOUT) on the underlying Net::Curl::Multi object. The return is the same as that operation returns.
Since process() can also do the work of this function, a call to this function is just an optimization.
process()
A passthrough to the underlying Net::Curl::Multi object’s method of the same name. Returns OBJ to facilitate chaining.
IMPORTANT: Don’t set CURLMOPT_SOCKETFUNCTION or CURLMOPT_SOCKETDATA. OBJ needs to set those internally.
CURLMOPT_SOCKETFUNCTION
CURLMOPT_SOCKETDATA
A passthrough to the underlying Net::Curl::Multi object’s method of the same name.
To use Net::Curl::Promiser, you’ll need a subclass that defines the following methods:
_INIT(\@ARGS): Called at the end of new(). Receives a reference to the arguments given to new().
_INIT(\@ARGS)
_SET_POLL_IN($FD): Tells the event loop that the given file descriptor is ready to read.
_SET_POLL_IN($FD)
_SET_POLL_OUT($FD): Like _SET_POLL_IN() but for a write event.
_SET_POLL_OUT($FD)
_SET_POLL_IN()
_SET_POLL_INOUT($FD): Like _SET_POLL_IN() but registers a read and write event simultaneously.
_SET_POLL_INOUT($FD)
_STOP_POLL($FD): Tells the event loop that the given file descriptor is finished.
_STOP_POLL($FD)
_GET_FD_ACTION(\@ARGS): Receives a reference to the arguments given to process() and returns a reference to a hash of ( $fd => $event_mask ). $event_mask is the sum of Net::Curl::Multi::CURL_CSELECT_IN() and/or Net::Curl::Multi::CURL_CSELECT_OUT(), depending on which events are available.
_GET_FD_ACTION(\@ARGS)
Net::Curl::Multi::CURL_CSELECT_IN()
Net::Curl::Multi::CURL_CSELECT_OUT()
See the distribution’s /examples directory.
If you use AnyEvent, then AnyEvent::XSPromises with AnyEvent::YACurl may be a nicer fit for you.
https://github.com/FGasper/p5-Net-Curl-Promiser
Copyright 2019 Gasper Software Consulting.
This library is licensed under the same terms as Perl itself.
To install Net::Curl::Promiser, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Curl::Promiser
CPAN shell
perl -MCPAN -e shell install Net::Curl::Promiser
For more information on module installation, please visit the detailed CPAN module installation guide.