=head1 NAME

IO::Mux::Handler::Write - any mux writer

=head1 INHERITANCE

 IO::Mux::Handler::Write
   is a IO::Mux::Handler

 IO::Mux::Handler::Write is extended by
   IO::Mux::Bundle
   IO::Mux::File::Write
   IO::Mux::Net::TCP
   IO::Mux::Pipe::Write

=head1 SYNOPSIS

  # only use extensions

=head1 DESCRIPTION

In an event driven program, you must be careful with every Operation
System call, because it can block the event mechanism, hence the program
as a whole. Often you can be lazy with writes, because its communication
buffers are usually working quite asynchronous... but not always. You
may skip the callbacks for small writes and prints.

=head1 METHODS

=head2 Constructors

=over 4

=item IO::Mux::Handler::Write-E<gt>B<new>(OPTIONS)

 -Option    --Defined in     --Default
  fh          IO::Mux::Handler  <required>
  name        IO::Mux::Handler  <stringified handle>
  write_size                   4096

=over 2

=item fh => FILEHANDLE

=item name => STRING

=item write_size => INTEGER

=back

=item IO::Mux::Handler::Write-E<gt>B<open>(MODE, WHAT, OPTIONS)
See L<IO::Mux::Handler/"Constructors">

=back

=head2 Accessors

=over 4

=item $obj-E<gt>B<fh>
See L<IO::Mux::Handler/"Accessors">

=item $obj-E<gt>B<fileno>
See L<IO::Mux::Handler/"Accessors">

=item $obj-E<gt>B<mux>
See L<IO::Mux::Handler/"Accessors">

=item $obj-E<gt>B<name>
See L<IO::Mux::Handler/"Accessors">

=item $obj-E<gt>B<usesSSL>
See L<IO::Mux::Handler/"Accessors">

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

The number of bytes written at each write.

=back

=head2 User interface

=head3 Connection

=over 4

=item $obj-E<gt>B<close>([CALLBACK])
See L<IO::Mux::Handler/"Connection">

=item $obj-E<gt>B<timeout>([TIMEOUT])
See L<IO::Mux::Handler/"Connection">

=back

=head3 Writing

=over 4

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

Send one or more lines to the output. The data is packed into a
single string first. The ARRAY (of strings) and SCALAR (ref string)
choices are available for efficiency.

example: 

  $conn->print($some_text);
  $conn->print(\$some_text);

  my $fh = $conn->fh;
  print $fh "%s%d%X", $foo, $bar, $baz;

=item $obj-E<gt>B<printf>(FORMAT, PARAMS)

example: 

    $conn->printf("%s%d%X", $foo, $bar, $baz);

    my $fh = $conn->fh;
    $fh->printf("%s%d%X", $foo, $bar, $baz);

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

Like L<print()|IO::Mux::Handler::Write/"Writing"> but adding a newline at the end.

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

Send the content of the string, passed as reference in SCALAR. You
probably want to use L<print()|IO::Mux::Handler::Write/"Writing"> or L<printf()|IO::Mux::Handler::Write/"Writing">.  You may provide
a code reference to produce MORE info when the output buffer get
empty.

=back

=head2 Multiplexer

=head3 Connection

=over 4

=item $obj-E<gt>B<mux_init>(MUX, [HANDLER])
See L<IO::Mux::Handler/"Connection">

=item $obj-E<gt>B<mux_remove>
See L<IO::Mux::Handler/"Connection">

=item $obj-E<gt>B<mux_timeout>
See L<IO::Mux::Handler/"Connection">

=back

=head3 Reading

=over 4

=item $obj-E<gt>B<mux_except_flagged>(FILENO)
See L<IO::Mux::Handler/"Reading">

=item $obj-E<gt>B<mux_read_flagged>(FILENO)
See L<IO::Mux::Handler/"Reading">

=back

=head3 Writing

=over 4

=item $obj-E<gt>B<mux_outbuffer_empty>

Called after all pending output has been written to the file descriptor.
You may use this callback to produce more data to be written.

When this method is not overruled, the multiplexer will stop listening
to the write flag until an explicit L<write()|IO::Mux::Handler::Write/"Writing"> gets executed.

example: 

  package My::Service;
  use base 'IO::Mux::Net::TCP';

  sub mux_outbuffer_empty()
  {   my $self = shift;
      if(my $data = $self->produce_more_data)
      {   $self->write(\$data);
      }
      else
      {   $self->SUPER::mux_outbuffer_empty;
      }
  }

=item $obj-E<gt>B<mux_output_waiting>

Returns true is there is output queued.

=item $obj-E<gt>B<mux_write_flagged>(FILENO)
See L<IO::Mux::Handler/"Writing">

=back

=head3 Service

=head2 Helpers

=over 4

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

=item IO::Mux::Handler::Write-E<gt>B<extractSocket>(HASH)
See L<IO::Mux::Handler/"Helpers">

=item $obj-E<gt>B<fdset>(STATE, READ, WRITE, ERROR)
See L<IO::Mux::Handler/"Helpers">

=item $obj-E<gt>B<show>
See L<IO::Mux::Handler/"Helpers">

=back

=head1 SEE ALSO

This module is part of IO-Mux distribution version 0.11,
built on January 26, 2011. Website: F<http://perl.overmeer.net/>
All modules in this suite:
L</Any::Daemon>,
L</IO::Mux>, and
L</IO::Mux::HTTP>.

Please post questions or ideas to F<perl@overmeer.net>

=head1 LICENSE

Copyrights 2011 by Mark Overmeer. 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://www.perl.com/perl/misc/Artistic.html>

