/ 
BSD-Socket-Splice-0.04
River stage zero No dependents
/ BSD::Socket::Splice

NAME

BSD::Socket::Splice - Perl interface to OpenBSD socket splicing

SYNOPSIS

use BSD::Socket::Splice;

$so = new IO::Socket;
$sosp = new IO::Socket;
setsplice($so, $sosp);
setsplice($so, $sosp, $max);
setsplice($so, $sosp, $max, $idle);
setsplice($so);

$len = getsplice($so);
$errno = geterror($so);

DESCRIPTION

The BSD::Socket::Splice module implements a Perl interface to OpenBSD socket splicing. This allows zero-copy data transfer between TCP sockets. Compared to invoking the system calls manually with pack() and setsockopt(), the module provides a convenient and machine independent way to access the kernel.

Nothing is exported by default, the following functions can be exported on demand:

setsplice($so, $sosp), setsplice($so, $sosp, $max), setsplice($so, $sosp, $max, $idle), setsplice($so)

Splice together the source socket $so and the drain socket $sosp. Then the kernel will move network data from $so to $sosp without further user-land interaction. For bidirectional splicing two function-calls with exchanged socket parameters are necessary.

The second form allows to specify a maximum number bytes to transfer. Note that a short splice might happen which means that fewer data has been moved. If that has happened, a second call pointing to the same maximum will succeed and move the outstanding data.

The third form allows to specify an idle timeout for the connection.

Splicing of two sockets will get dissolved automatically in case of end-of-file at the source socket, if a read or write error occurred or if the optional maximum has been reached. An existing splicing can be dissolved manually by using the fourth form.

getsplice($so)

Return the number of bytes already transfered from this socket by splicing.

geterror($so)

Return the error number attached to this socket. This is not specific to splicing but is added here for convenience. All errors during data transfer can be retrieved from the source socket.

SO_SPLICE

Return the kernel constant for the socket splicing socket option. It is not necessary to use this constant as the kernel interface is encapsulated by this module.

ERRORS

When called with bad argument types the functions carp. In general setsplice(), getsplice(), geterror() set $! and return undef in case of an error. setsplice() and getsplice() try to convert between the off_t value of the operating system and Perl's integer and numeric value automatically. If they fail to do so, they set $! to EINVAL and return undef.

SEE ALSO

setsockopt(2), sosplice(9)

AUTHOR

Alexander Bluhm <bluhm@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2010,2011 by Alexander Bluhm

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.12.2 or, at your option, any later version of Perl 5 you may have available.