/ 
WWW-CurlOO-0.12
/ WWW::CurlOO::Multi

NAME

WWW::CurlOO::Multi - Perl interface for curl_multi_* functions

WARNING

THIS MODULE IS UNDER HEAVY DEVELOPEMENT AND SOME INTERFACE MAY CHANGE YET.

SYNOPSIS

use WWW::CurlOO::Multi qw(:constants);

my $multi = WWW::CurlOO::Multi->new();
$multi->add_handle( $easy );

my $running = 0;
do {
    my ($r, $w, $e) = $multi->fdset();
    my $timeout = $multi->timeout();
    select $r, $w, $e, $timeout / 1000
        if $timeout > 0;

    $running = $multi->perform();
    while ( my ( $msg, $easy, $result ) = $multi->info_read() ) {
        $multi->remove_handle( $easy );

        # process $easy
    }
} while ( $running );

DESCRIPTION

This module wraps multi handle from libcurl and all related functions and constants. It does not export by default anything, but constants can be exported upon request.

use WWW::CurlOO::Multi qw(:constants);

CONSTRUCTOR

new( [BASE] )

Creates new WWW::CurlOO::Multi object. If BASE is specified it will be used as object base, otherwise an empty hash will be used. BASE must be a valid reference which has not been blessed already. It will not be used by the object.

my $multi = WWW::CurlOO::Multi->new( [qw(my very private data)] );

Calls curl_multi_init(3) and presets some defaults.

METHODS

add_handle( EASY )

Add WWW::CurlOO::Easy to this WWW::CurlOO::Multi object.

$multi->add_handle( $easy );

Calls curl_multi_add_handle(3).

remove_handle( EASY )

Remove WWW::CurlOO::Easy from this WWW::CurlOO::Multi object.

$multi->remove_handle( $easy );

Calls curl_multi_remove_handle(3).

info_read( )

Read last message from this Multi.

my ( $msg, $easy, $result ) = $multi->info_read();

Calls curl_multi_info_read(3).

fdset( )

Returns read, write and exception vectors suitable for select() and vec() perl builtins.

my ( $rvec, $wvec, $evec ) = $multi->fdset();

Calls curl_multi_fdset(3).

timeout( )

Returns timeout value.

my $timeout_ms = $multi->timeout();

Calls curl_multi_timeout(3).

setopt( OPTION, VALUE )

Set an option. OPTION is a numeric value, use one of CURLMOPT_* constants. VALUE depends on whatever that option expects.

$multi->setopt( CURLMOPT_MAXCONNECTS, 10 );

Calls curl_multi_setopt(3).

perform( )

Perform.

my $active = $multi->perform();

Calls curl_multi_perform(3).

socket_action( [SOCKET], [BITMASK] )

Signalize action on a socket.

my $active = $multi->socket_action();

# there is data to read on socket:
my $active = $multi->socket_action( $socket, CURL_CSELECT_IN );

Calls curl_multi_socket_action(3).

assign( SOCKET, [VALUE] )

Assigns some value to a socket file descriptor. Removes it is value is not specified.

Calls curl_multi_assign(3).

handles( )

In list context returns easy handles attached to this multi. In scalar context returns number of easy handles attached.

There is no libcurl equivalent.

DESTROY( )

Cleans up. It should not be called manually.

Calls curl_multi_cleanup(3).

FUNCTIONS

None of those functions are exported, you must use fully qualified names.

strerror( [WHATEVER], CODE )

Return a string for error code CODE.

my $message = $multi->strerror( CURLM_BAD_EASY_HANDLE );

See curl_multi_strerror(3) for more info.

CONSTANTS

CURLM_*

If any method fails, it will return one of those values.

CURLMSG_*

Message type from info_read().

CURLMOPT_*

Option values for setopt().

CURL_POLL_*

Poll action information for socket callback.

CURL_CSELECT_*

Select bits for socket_action() method.

CURL_SOCKET_TIMEOUT

Special socket value for socket_action() method.

CALLBACKS

CURLMOPT_SOCKETFUNCTION ( CURLMOPT_SOCKETDATA )

Socket callback will be called only if socket_action() method is being used. It receives 6 arguments: multi handle, easy handle, socket file number, poll action, an undefined value (for now), and CURLMOPT_SOCKETDATA value. It must return 0. For more information reffer to curl_multi_socket_action(3).

sub cb_socket {
    my ( $multi, $easy, $socketfn, $action, $undef, $uservar ) = @_;
    # ... register or deregister socket actions ...
    return 0;
}
CURLMOPT_TIMERFUNCTION ( CURLMOPT_TIMERDATA ) 7.16.0+

Timer callback receives 3 arguments: multi object, timeout in ms, and CURLMOPT_TIMERDATA value. Should return 0.

sub cb_timer {
    my ( $multi, $timeout_ms, $uservar ) = @_;
    # ... update timeout ...
    return 0;
}

SEE ALSO

WWW::CurlOO WWW::CurlOO::Easy WWW::CurlOO::examples(3pm) libcurl-multi(3) libcurl-errors(3)

COPYRIGHT

Copyright (c) 2011 Przemyslaw Iskra <sparky at pld-linux.org>.

You may opt to use, copy, modify, merge, publish, distribute and/or sell copies of the Software, and permit persons to whom the Software is furnished to do so, under the terms of the MPL or the MIT/X-derivate licenses. You may pick one of these licenses.