IO::Mux::Handle - Virtual handle used with the L multiplexer.

SYNOPSIS

  use IO::Mux ;

  my $mux = new IO::Mux(\*SOCKET) ;
  my $iomh = new IO::Mux::Handle($mux) ;

  open($iomh, "identifier") or die("Can't open: " . $io->get_error()) ;
  print $iomh "hello\n" ;
  while (<$iomh>){ 
    print $_ ;
  }
  close($iomh) ;

DESCRIPTION

IO::Mux::Handle objects are used to create virtual handles that are multiplexed through an the IO::Mux manpage object.

CONSTRUCTOR

new ( IOMUX ): Creates a new IO::Mux::Handle that is multiplexed over the real handle managed by IOMUX.

METHODS

Since IO::Mux::Handle extends the IO::Handle manpage, most the IO::Handle manpage methods that make sense in this context are supported. The corresponding builtins can also be used. Errors are reported using the standard return values and mechanisms. See below (ERROR REPORTING in the IO::Mux::Handle manpage) for more details.

$iomh->open ( ID )

Opens $iomh and associates it with the identifier ID. ID can be any scalar value, but any tabs ('\t') in ID will be replaced by spaces (' ') in order to make it compatible with the underlying multiplexing protocol.

Returns 1 on success or undef on error (the error message can be retreived by calling $iomh->get_error()).

$iomh->fileno ()

Since there is no real filehandle associated with IO::Mux::Handle objects, $iomh->fileno() returns the ID identifier that was passed to $iomh->open().

$iomh->get_error ()

Returns the last error associated with $iomh.

ERROR REPORTING

While manipulating IO::Mux::Handle objects, two types of errors can occur:

Errors encountered on the real underlying handle

When error occurs on the underlying (real) handle, $! is set as usual and the approriate return code is used.

Errors generated by IO::Mux::* module code

Sometimes errors can be generated by the IO::Mux:* code itself. In this case, $! is set to EIO if possible (see the Errno manpage for more details). If EIO does not exists on your system, $! is set to 99999. Also, the actual IO::Mux::* error message can be retrieved by calling $iomh->get_error().

Therefore, when working with IO::Mux::Handle objects, it is always a good idea to check $iomh->get_error() when $! is supposed to be set, i.e.:

  print $iomh "hi!\n" or die("Can't print: $! (" . $iomh->get_error() . ")") ;

AUTHOR

Patrick LeBoutillier, <patl@cpan.org>

COPYRIGHT AND LICENSE

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

IO::Mux::Handle - Virtual handle used with the L multiplexer.