NAME

Kafka::IO - Interface to network communication with the Apache Kafka server.

VERSION

This documentation refers to "Kafka::IO" version 0.8010 .

SYNOPSIS

    use 5.010;
    use strict;
    use warnings;
    use Scalar::Util qw(
        blessed
    );
    use Try::Tiny;
    use Kafka::IO;
    my $io;
    try {
        $io = Kafka::IO->new( host => 'localhost' );
    } catch {
        if ( blessed( $_ ) && $_->isa( 'Kafka::Exception' ) ) {
            warn 'Error: (', $_->code, ') ',  $_->message, "\n";
            exit;
        } else {
            die $_;
        }
    };
    # Closes and cleans up
    $io->close;
    undef $io;

DESCRIPTION

This module is private and should not be used directly.

In order to achieve better performance, methods of this module do not perform arguments validation.

The main features of the "Kafka::IO" class are:

Provides an object oriented API for communication with Kafka.
This class allows you to create Kafka 0.8 clients.

CONSTRUCTOR

"new"

Establishes TCP connection to given host and port, creates and returns "Kafka::IO" IO object.

new() takes arguments in key-value pairs. The following arguments are currently recognized:

"host => $host"

$host is an Apache Kafka host to connect to. It can be a hostname or the IP-address in the "xx.xx.xx.xx" form.

"port => $port"

Optional, default = $KAFKA_SERVER_PORT.

$port is integer attribute denoting the port number of to access Apache Kafka.

$KAFKA_SERVER_PORT is the default Apache Kafka server port that can be imported from the Kafka module.

"timeout => $timeout"

Optional, default = $REQUEST_TIMEOUT.

$timeout specifies how long we wait for remote server to respond before the IO object disconnects and throws internal exception. The $timeout is specified in seconds (could be any integer or floating-point type) and supported by gethostbyname(), connect, blocking receive and send calls.

$REQUEST_TIMEOUT is the default timeout that can be imported from the Kafka module.

Special behavior when "timeout" is set to "undef":

Alarms are not used internally (namely when performing "gethostbyname").
Default $REQUEST_TIMEOUT is used for the rest of IO operations.

METHODS

The following methods are provided by "Kafka::IO" class:

send( $message )

Sends a $message to Kafka.

The argument must be a bytes string.

Returns the number of characters sent.

receive( $length )

Receives a message up to $length size from Kafka.

$length argument must be a positive number.

Returns a reference to the received message.

"close"

Closes connection to Kafka server.

"is_alive"

The method verifies whether we are connected to Kafka server.

DIAGNOSTICS

When error is detected, an exception, represented by object of "Kafka::Exception::Producer" class, is thrown (see Kafka::Exceptions).

code and a more descriptive message provide information about thrown exception. Consult documentation of the Kafka::Exceptions for the list of all available methods.

Authors suggest using of Try::Tiny's "try" and "catch" to handle exceptions while working with Kafka package.

Here is the list of possible error messages that "Kafka::IO" may produce:

"Invalid argument": Invalid arguments were passed to a method.
"Can't send": Message can't be sent on a "Kafka::IO" object socket.
"Can't recv": Message can't be received.
"Can't bind": TCP connection can't be established on given host and port.

Debug mode

Debug output can be enabled by passing desired level via environment variable using one of the following ways:

"PERL_KAFKA_DEBUG=1" - debug is enabled for the whole Kafka package.

"PERL_KAFKA_DEBUG=IO:1" - enable debug for "Kafka::IO" only.

"Kafka::IO" supports two debug levels (level 2 includes debug output of 1):

1.: Additional information about processing events/alarms.
2.: Dump of binary messages exchange with Kafka server.

SOURCE CODE

Kafka package is hosted on GitHub: <https://github.com/TrackingSoft/Kafka>

AUTHOR

Sergey Gladkov, <sgladkov@trackingsoft.com>

CONTRIBUTORS

Alexander Solovey

Jeremy Jordan

Sergiy Zuban

Vlad Marchenko

COPYRIGHT AND LICENSE

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

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.