=encoding utf8

=head1 NAME

IOMux::Net::TCP - handle a TCP connection

=head1 INHERITANCE

 IOMux::Net::TCP
   is an IOMux::Handler::Read
   is an IOMux::Handler

 IOMux::Net::TCP
   is an IOMux::Handler::Write
   is an IOMux::Handler

=head1 SYNOPSIS

=head1 DESCRIPTION

Handle a service or locally initiated TCP connection.

Extends L<"DESCRIPTION" in IOMux::Handler::Write|IOMux::Handler::Write/"DESCRIPTION">.
 
Extends L<"DESCRIPTION" in IOMux::Handler::Read|IOMux::Handler::Read/"DESCRIPTION">.
 
=head1 METHODS

Extends L<"METHODS" in IOMux::Handler::Write|IOMux::Handler::Write/"METHODS">.
 
Extends L<"METHODS" in IOMux::Handler::Read|IOMux::Handler::Read/"METHODS">.
 
=head2 Constructors

Extends L<"Constructors" in IOMux::Handler::Write|IOMux::Handler::Write/"Constructors">.
 
Extends L<"Constructors" in IOMux::Handler::Read|IOMux::Handler::Read/"Constructors">.
 
=over 4

=item IOMux::Net::TCP-E<gt>B<new>(%options)

Build a connection as client or server. You may either pass an prepared
C<socket> object or parameters to initiate one. All %options which start
with capitals are passed to the socket creation. See L<extractSocket()|IOMux::Handler/"Helpers">
for those additional %options.

 -Option    --Defined in           --Default
  fh          IOMux::Handler         <required>
  name        IOMux::Handler         'tcp $host:$port'
  read_size   IOMux::Handler::Read   32768
  socket                             <required>
  write_size  IOMux::Handler::Write  4096

=over 2

=item fh => FILEHANDLE

=item name => STRING

=item read_size => INTEGER

=item socket => IO::Socket::INET

Provide a socket, either as object or the parameters to instantiate it.

=item write_size => INTEGER

=back

example: 

  # long form, most flexible
  my $socket = IO::Socket::INET->new(PeerAddr => 'www.example.com:80');
  my $client = IOMux::Net::TCP->new(socket => $socket);
  $mux->add($client);

  # short form
  my $client = IOMux::Net::TCP->new(PeerAddr => 'www.example.com:80');
  $mux->add($client);

  # even shorter
  my $client = $mux->open('tcp', PeerAddr => 'www.example.com:80');

=item IOMux::Net::TCP-E<gt>B<open>($mode, $what, %options)

Inherited, see L<IOMux::Handler/"Constructors">

=item IOMux::Net::TCP-E<gt>B<open>($mode, $what, %options)

Inherited, see L<IOMux::Handler/"Constructors">

=back

=head2 Accessors

Extends L<"Accessors" in IOMux::Handler::Write|IOMux::Handler::Write/"Accessors">.
 
Extends L<"Accessors" in IOMux::Handler::Read|IOMux::Handler::Read/"Accessors">.
 
=over 4

=item $obj-E<gt>B<fh>()

Inherited, see L<IOMux::Handler/"Accessors">

=item $obj-E<gt>B<fh>()

Inherited, see L<IOMux::Handler/"Accessors">

=item $obj-E<gt>B<fileno>()

Inherited, see L<IOMux::Handler/"Accessors">

=item $obj-E<gt>B<fileno>()

Inherited, see L<IOMux::Handler/"Accessors">

=item $obj-E<gt>B<mux>()

Inherited, see L<IOMux::Handler/"Accessors">

=item $obj-E<gt>B<mux>()

Inherited, see L<IOMux::Handler/"Accessors">

=item $obj-E<gt>B<name>()

Inherited, see L<IOMux::Handler/"Accessors">

=item $obj-E<gt>B<name>()

Inherited, see L<IOMux::Handler/"Accessors">

=item $obj-E<gt>B<readSize>( [$integer] )

Inherited, see L<IOMux::Handler::Read/"Accessors">

=item $obj-E<gt>B<socket>()

=item $obj-E<gt>B<usesSSL>()

Inherited, see L<IOMux::Handler/"Accessors">

=item $obj-E<gt>B<usesSSL>()

Inherited, see L<IOMux::Handler/"Accessors">

=item $obj-E<gt>B<writeSize>( [$integer] )

Inherited, see L<IOMux::Handler::Write/"Accessors">

=back

=head2 User interface

Extends L<"User interface" in IOMux::Handler::Write|IOMux::Handler::Write/"User interface">.
 
Extends L<"User interface" in IOMux::Handler::Read|IOMux::Handler::Read/"User interface">.
 
=head3 Connection

Extends L<"Connection" in IOMux::Handler::Write|IOMux::Handler::Write/"Connection">.
 
Extends L<"Connection" in IOMux::Handler::Read|IOMux::Handler::Read/"Connection">.
 
=over 4

=item $obj-E<gt>B<close>( [$callback] )

Inherited, see L<IOMux::Handler/"Connection">

=item $obj-E<gt>B<close>( [$callback] )

Inherited, see L<IOMux::Handler/"Connection">

=item $obj-E<gt>B<shutdown>( <0|1|2> )

Shut down a socket for reading or writing or both. See the C<shutdown>
Perl documentation for further details.

If the shutdown is for reading (0 or 2), it happens immediately. However,
shutdowns for writing (1 or 2) are delayed until any pending output has
been successfully written to the socket.

example: 

  $conn->shutdown(1);

=item $obj-E<gt>B<timeout>( [$timeout] )

Inherited, see L<IOMux::Handler/"Connection">

=item $obj-E<gt>B<timeout>( [$timeout] )

Inherited, see L<IOMux::Handler/"Connection">

=back

=head3 Reading

Extends L<"Reading" in IOMux::Handler::Read|IOMux::Handler::Read/"Reading">.
 
=over 4

=item $obj-E<gt>B<readline>($callback)

Inherited, see L<IOMux::Handler::Read/"Reading">

=item $obj-E<gt>B<slurp>($callback)

Inherited, see L<IOMux::Handler::Read/"Reading">

=back

=head3 Writing

Extends L<"Writing" in IOMux::Handler::Write|IOMux::Handler::Write/"Writing">.
 
=over 4

=item $obj-E<gt>B<print>(STRING|SCALAR|LIST|ARRAY)

Inherited, see L<IOMux::Handler::Write/"Writing">

=item $obj-E<gt>B<printf>($format, $params)

Inherited, see L<IOMux::Handler::Write/"Writing">

=item $obj-E<gt>B<say>(STRING|SCALAR|LIST|ARRAY)

Inherited, see L<IOMux::Handler::Write/"Writing">

=item $obj-E<gt>B<write>( SCALAR, [$more] )

Inherited, see L<IOMux::Handler::Write/"Writing">

=back

=head2 Multiplexer

Extends L<"Multiplexer" in IOMux::Handler::Write|IOMux::Handler::Write/"Multiplexer">.
 
Extends L<"Multiplexer" in IOMux::Handler::Read|IOMux::Handler::Read/"Multiplexer">.
 
=head3 Connection

Extends L<"Connection" in IOMux::Handler::Write|IOMux::Handler::Write/"Connection">.
 
Extends L<"Connection" in IOMux::Handler::Read|IOMux::Handler::Read/"Connection">.
 
=over 4

=item $obj-E<gt>B<muxInit>( $mux, [$handler] )

Inherited, see L<IOMux::Handler/"Connection">

=item $obj-E<gt>B<muxInit>( $mux, [$handler] )

Inherited, see L<IOMux::Handler/"Connection">

=item $obj-E<gt>B<muxRemove>()

Inherited, see L<IOMux::Handler/"Connection">

=item $obj-E<gt>B<muxRemove>()

Inherited, see L<IOMux::Handler/"Connection">

=item $obj-E<gt>B<muxTimeout>()

Inherited, see L<IOMux::Handler/"Connection">

=item $obj-E<gt>B<muxTimeout>()

Inherited, see L<IOMux::Handler/"Connection">

=back

=head3 Reading

Extends L<"Reading" in IOMux::Handler::Write|IOMux::Handler::Write/"Reading">.
 
Extends L<"Reading" in IOMux::Handler::Read|IOMux::Handler::Read/"Reading">.
 
=over 4

=item $obj-E<gt>B<muxEOF>()

For sockets, this does not nessecarily mean that the descriptor has been
closed, as the other end of a socket could have used L<shutdown()|IOMux::Net::TCP/"Connection"> to
close just half of the socket, leaving us free to write data back down
the still open half.

example: 

In this example, we send a final reply to the other end of the socket,
and then shut it down for writing.  Since it is also shut down for reading
(implicly by the EOF condition), it will be closed once the output has
been sent, after which the L<close()|IOMux::Handler/"Connection"> callback will be called.

  sub muxEOF
  {   my ($self, $ref_input) = @_;
      print $fh "Well, goodbye then!\n";
      $self->shutdown(1);
  }

=item $obj-E<gt>B<muxExceptFlagged>($fileno)

Inherited, see L<IOMux::Handler/"Reading">

=item $obj-E<gt>B<muxExceptFlagged>($fileno)

Inherited, see L<IOMux::Handler/"Reading">

=item $obj-E<gt>B<muxInput>($buffer)

Inherited, see L<IOMux::Handler::Read/"Reading">

=item $obj-E<gt>B<muxReadFlagged>($fileno)

Inherited, see L<IOMux::Handler/"Reading">

=item $obj-E<gt>B<muxReadFlagged>($fileno)

Inherited, see L<IOMux::Handler/"Reading">

=back

=head3 Writing

Extends L<"Writing" in IOMux::Handler::Write|IOMux::Handler::Write/"Writing">.
 
Extends L<"Writing" in IOMux::Handler::Read|IOMux::Handler::Read/"Writing">.
 
=over 4

=item $obj-E<gt>B<muxOutbufferEmpty>()

Inherited, see L<IOMux::Handler::Write/"Writing">

=item $obj-E<gt>B<muxOutputWaiting>()

Inherited, see L<IOMux::Handler::Write/"Writing">

=item $obj-E<gt>B<muxWriteFlagged>($fileno)

Inherited, see L<IOMux::Handler/"Writing">

=item $obj-E<gt>B<muxWriteFlagged>($fileno)

Inherited, see L<IOMux::Handler/"Writing">

=back

=head3 Service

Extends L<"Service" in IOMux::Handler::Write|IOMux::Handler::Write/"Service">.
 
Extends L<"Service" in IOMux::Handler::Read|IOMux::Handler::Read/"Service">.
 
=head2 Helpers

Extends L<"Helpers" in IOMux::Handler::Write|IOMux::Handler::Write/"Helpers">.
 
Extends L<"Helpers" in IOMux::Handler::Read|IOMux::Handler::Read/"Helpers">.
 
=over 4

=item $obj-E<gt>B<extractSocket>(HASH)

=item IOMux::Net::TCP-E<gt>B<extractSocket>(HASH)

Inherited, see L<IOMux::Handler/"Helpers">

=item $obj-E<gt>B<extractSocket>(HASH)

=item IOMux::Net::TCP-E<gt>B<extractSocket>(HASH)

Inherited, see L<IOMux::Handler/"Helpers">

=item $obj-E<gt>B<fdset>($state, $read, $write, $error)

Inherited, see L<IOMux::Handler/"Helpers">

=item $obj-E<gt>B<fdset>($state, $read, $write, $error)

Inherited, see L<IOMux::Handler/"Helpers">

=item $obj-E<gt>B<show>()

Inherited, see L<IOMux::Handler/"Helpers">

=item $obj-E<gt>B<show>()

Inherited, see L<IOMux::Handler/"Helpers">

=back

=head1 SEE ALSO

This module is part of IOMux distribution version 1.01,
built on January 15, 2020. Website: F<http://perl.overmeer.net/CPAN>

=head1 LICENSE

Copyrights 2011-2020 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://dev.perl.org/licenses/>