# NAME Net::Curl::Promiser - A Promise interface for [Net::Curl::Multi](https://metacpan.org/pod/Net::Curl::Multi) # DESCRIPTION This module wraps [Net::Curl::Multi](https://metacpan.org/pod/Net::Curl::Multi) to facilitate asynchronous HTTP requests with Promise objects. [Net::Curl::Promiser](https://metacpan.org/pod/Net::Curl::Promiser) itself is a base class; you’ll need to provide an interface to whatever event loop you use. See ["SUBCLASS INTERFACE"](#subclass-interface) below. This distribution provides [Net::Curl::Promiser::Select](https://metacpan.org/pod/Net::Curl::Promiser::Select) and [Net::Curl::Promiser::AnyEvent](https://metacpan.org/pod/Net::Curl::Promiser::AnyEvent) as both demonstrations and easily portable implementations. See the distribution’s `/examples` directory for another. # PROMISE IMPLEMENTATION This class’s default Promise implementation is [Promise::ES6](https://metacpan.org/pod/Promise::ES6). You can use a different one by overriding the [PROMISE\_CLASS()](https://metacpan.org/pod/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). # METHODS ## _CLASS_->new(@ARGS) Instantiates this class. This creates an underlying [Net::Curl::Multi](https://metacpan.org/pod/Net::Curl::Multi) object and calls the subclass’s `_INIT()` method at the end, passing a reference to @ARGS. ## promise($EASY) = _OBJ_->add\_handle( $EASY ) A passthrough to the underlying [Net::Curl::Multi](https://metacpan.org/pod/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](https://metacpan.org/pod/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_->fail\_handle( $EASY, $REASON ) Prematurely fails $EASY. The given $REASON will be the associated Promise object’s rejection value. ## $num = _OBJ_->get\_timeout() Returns the underlying [Net::Curl::Multi](https://metacpan.org/pod/Net::Curl::Multi) object’s `timeout()` value, with a suitable (positive) default substituted if that value is less than 0. (NB: This value is in _milliseconds_.) This may not suit your needs; if you wish/need, you can handle timeouts via the [CURLMOPT\_TIMERFUNCTION](https://metacpan.org/pod/Net::Curl::Multi#CURLMOPT_TIMERFUNCTION) callback instead. ## $obj = _OBJ_->process( @ARGS ) Tell the underlying [Net::Curl::Multi](https://metacpan.org/pod/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](https://metacpan.org/pod/Net::Curl::Multi) object (similar to `time_out()`). `` Finally, this reaps whatever pending HTTP responses may be ready and resolves or rejects the corresponding Promise objects. Returns _OBJ_. ## $is\_active = _OBJ_->time\_out(); Tell the underlying [Net::Curl::Multi](https://metacpan.org/pod/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](https://metacpan.org/pod/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. ## $obj = _OBJ_->setopt( … ) A passthrough to the underlying [Net::Curl::Multi](https://metacpan.org/pod/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. ## $obj = _OBJ_->handles( … ) A passthrough to the underlying [Net::Curl::Multi](https://metacpan.org/pod/Net::Curl::Multi) object’s method of the same name. # SUBCLASS INTERFACE 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()`. - `_SET_POLL_IN($FD)`: Tells the event loop that the given file descriptor is ready to read. - `_SET_POLL_OUT($FD)`: Like `_SET_POLL_IN()` but for a write event. - `_SET_POLL_INOUT($FD)`: Like `_SET_POLL_IN()` but registers a read and write event simultaneously. - `_STOP_POLL($FD)`: Tells the event loop that the given file descriptor is finished. - `_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. # EXAMPLES See the distribution’s `/examples` directory. # SEE ALSO If you use [AnyEvent](https://metacpan.org/pod/AnyEvent), then [AnyEvent::XSPromises](https://metacpan.org/pod/AnyEvent::XSPromises) with [AnyEvent::YACurl](https://metacpan.org/pod/AnyEvent::YACurl) may be a nicer fit for you. # LICENSE & COPYRIGHT Copyright 2019 Gasper Software Consulting. This library is licensed under the same terms as Perl itself. # POD ERRORS Hey! **The above document had some coding errors, which are explained below:** - Around line 158: Unterminated C<...> sequence