IO::Async::Listener man page on Alpinelinux

Man page or keyword search:  
man Server   18016 pages
apropos Keyword Search (all sections)
Output format
Alpinelinux logo
[printable version]

IO::Async::Listener(3)User Contributed Perl DocumentatioIO::Async::Listener(3)

NAME
       "IO::Async::Listener" - listen on network sockets for incoming
       connections

SYNOPSIS
	use IO::Async::Listener;

	use IO::Async::Loop;
	my $loop = IO::Async::Loop->new;

	my $listener = IO::Async::Listener->new(
	   on_stream => sub {
	      my ( undef, $stream ) = @_;

	      $stream->configure(
		 on_read => sub {
		    my ( $self, $buffref, $eof ) = @_;
		    $self->write( $$buffref );
		    $$buffref = "";
		    return 0;
		 },
	      );

	      $loop->add( $stream );
	   },
	);

	$loop->add( $listener );

	$listener->listen(
	   service  => "echo",
	   socktype => 'stream',

	   on_resolve_error => sub { print STDERR "Cannot resolve - $_[0]\n"; },
	   on_listen_error  => sub { print STDERR "Cannot listen\n"; },
	);

	$loop->run;

       This object can also be used indirectly via an "IO::Async::Loop":

	use IO::Async::Stream;

	use IO::Async::Loop;
	my $loop = IO::Async::Loop->new;

	$loop->listen(
	   service  => "echo",
	   socktype => 'stream',

	   on_stream => sub {
	      ...
	   },

	   on_resolve_error => sub { print STDERR "Cannot resolve - $_[0]\n"; },
	   on_listen_error  => sub { print STDERR "Cannot listen\n"; },
	);

	$loop->run;

DESCRIPTION
       This subclass of IO::Async::Handle adds behaviour which watches a
       socket in listening mode, to accept incoming connections on them.

       A Listener can be constructed and given a existing socket in listening
       mode.  Alternatively, the Listener can construct a socket by calling
       the "listen" method. Either a list of addresses can be provided, or a
       service name can be looked up using the underlying loop's "resolve"
       method.

EVENTS
       The following events are invoked, either using subclass methods or CODE
       references in parameters:

   on_accept $clientsocket | $handle
       Invoked whenever a new client connects to the socket.

       If neither "handle_constructor" nor "handle_class" parameters are set,
       this will be invoked with the new client socket directly. If a handle
       constructor or class are set, this will be invoked with the newly-
       constructed handle, having the new socket already configured onto it.

   on_stream $stream
       An alternative to "on_accept", this an instance of IO::Async::Stream
       when a new client connects. This is provided as a convenience for the
       common case that a Stream object is required as the transport for a
       Protocol object.

       This is now vaguely deprecated in favour of using "on_accept" with a
       handle constructor or class.

   on_socket $socket
       Similar to "on_stream", but constructs an instance of
       IO::Async::Socket.  This is most useful for "SOCK_DGRAM" or "SOCK_RAW"
       sockets.

       This is now vaguely deprecated in favour of using "on_accept" with a
       handle constructor or class.

   on_accept_error $socket, $errno
       Optional. Invoked if the "accept" syscall indicates an error (other
       than "EAGAIN" or "EWOULDBLOCK"). If not provided, failures of "accept"
       will simply be ignored.

PARAMETERS
       The following named parameters may be passed to "new" or "configure":

       on_accept => CODE
       on_stream => CODE
       on_socket => CODE
	       CODE reference for the event handlers. Because of the mutually-
	       exclusive nature of their behaviour, only one of these may be
	       set at a time. Setting one will remove the other two.

       handle => IO
	       The IO handle containing an existing listen-mode socket.

       handle_constructor => CODE
	       Optional. If defined, gives a CODE reference to be invoked
	       every time a new client socket is accepted from the listening
	       socket. It is passed the listener object itself, and is
	       expected to return a new instance of "IO::Async::Handle" or a
	       subclass, used to wrap the new client socket.

		$handle = $handle_constructor->( $listener )

       handle_class => STRING
	       Optional. If defined and "handle_constructor" isn't, then new
	       wrapper handles are constructed by invoking the "new" method on
	       the given class name, passing in no additional parameters.

		$handle = $handle_class->new()

       acceptor => STRING|CODE
	       Optional. If defined, gives the name of a method or a CODE
	       reference to use to implement the actual accept behaviour. This
	       will be invoked as:

		$listener->acceptor( $socket ) ==> $accepted

		$listener->acceptor( $socket, handle => $handle ) ==> $handle

	       It is invoked with the listening socket as its its argument,
	       and optionally an "IO::Async::Handle" instance as a named
	       parameter, and is expected to return a "Future" that will
	       eventually yield the newly-accepted socket or handle instance,
	       if such was provided.

METHODS
   $acceptor = $listener->acceptor
       Returns the currently-set "acceptor" method name or code reference.
       This may be of interest to Loop "listen" extension methods that wish to
       extend or wrap it.

   $name = $listener->sockname
       Returns the "sockname" of the underlying listening socket

   $family = $listener->family
       Returns the socket address family of the underlying listening socket

   $socktype = $listener->socktype
       Returns the socket type of the underlying listening socket

   $listener->listen( %params )
       This method sets up a listening socket and arranges for the acceptor
       callback to be invoked each time a new connection is accepted on the
       socket.

       Most parameters given to this method are passed into the "listen"
       method of the IO::Async::Loop object. In addition, the following
       arguments are also recognised directly:

       on_listen => CODE
	       Optional. A callback that is invoked when the listening socket
	       is ready.  Similar to that on the underlying loop method,
	       except it is passed the listener object itself.

		$on_listen->( $listener )

EXAMPLES
   Listening on UNIX Sockets
       The "handle" argument can be passed an existing socket already in
       listening mode, making it possible to listen on other types of socket
       such as UNIX sockets.

	use IO::Async::Listener;
	use IO::Socket::UNIX;

	use IO::Async::Loop;
	my $loop = IO::Async::Loop->new;

	my $listener = IO::Async::Listener->new(
	   on_stream => sub {
	      my ( undef, $stream ) = @_;

	      $stream->configure(
		 on_read => sub {
		    my ( $self, $buffref, $eof ) = @_;
		    $self->write( $$buffref );
		    $$buffref = "";
		    return 0;
		 },
	      );

	      $loop->add( $stream );
	   },
	);

	$loop->add( $listener );

	my $socket = IO::Socket::UNIX->new(
	   Local => "echo.sock",
	   Listen => 1,
	) or die "Cannot make UNIX socket - $!\n";

	$listener->listen(
	   handle => $socket,
	);

	$loop->run;

   Passing Plain Socket Addresses
       The "addr" or "addrs" parameters should contain a definition of a plain
       socket address in a form that the IO::Async::OS "extract_addrinfo"
       method can use.

       This example shows how to use the "Socket" functions to construct one
       for TCP port 8001 on address 10.0.0.1:

	$listener->listen(
	   addr => {
	      family   => "inet",
	      socktype => "stream",
	      port     => 8001,
	      ip       => "10.0.0.1",
	   },
	   ...
	);

       This example shows another way to listen on a UNIX socket, similar to
       the earlier example:

	$listener->listen(
	   addr => {
	      family   => "unix",
	      socktype => "stream",
	      path     => "echo.sock",
	   },
	   ...
	);

AUTHOR
       Paul Evans <leonerd@leonerd.org.uk>

perl v5.18.2			  2014-05-14		IO::Async::Listener(3)
[top]

List of man pages available for Alpinelinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net