# NAME

Net::Bullfinch - Perl wrapper for talking with Bullfinch

# VERSION

version 0.11

# SYNOPSIS

    use Net::Bullfinch;

    my $client = Net::Bullfinch->new(host => '172.16.49.130');
    my $req = { statement => 'some-query' };
    my $items = $client->send(
        request_queue => 'test-net-kestrel',
        request => $req,
        response_queue_suffix => 'foobar'
    );
    foreach my $item (@{ $items }) {
        # whatever
    }

# DESCRIPTION

Net::Bullfinch is a thin wrapper around [Memcached::Client](http://search.cpan.org/perldoc?Memcached::Client) for communicating with
a [Bullfinch](https://github.com/gphat/bullfinch/).

This module handles JSON encoding of the request, the addition of a response
queue, waiting for a response, confirmation of the message, decoding of the
response and deletion of the response queue.

If you're expecting large numbers of results you might enjoy using
[Net::Bullfinch::Iterator](http://search.cpan.org/perldoc?Net::Bullfinch::Iterator) to return any given number of max_results at a time.

# TRACING

Bullfinch supports adding a tracing a request so that performance metrics
and responses can be tracked.

    my $items = $client->send(
        request_queue => 'test-net-kestrel',
        request => $req,
        response_queue_suffix => 'foobar'
        trace => 1
    );

A UUID will be added to the request.  This UUID will be included in the
performance code in bullfinch workers and included in the response you
receive.

# ATTRIBUTES

## host

The IP address of the host that we'll be connecting to.

## port

The port of the IP address of the host we'll be connecting to.

## response_prefix

The prefix used for the name of the response queue.

## timeout

Set the timeout (in milliseconds) that will be used when awaiting a response
back from Bullfinch.

## error_on_no_response

Set an error explicitly when there is no response from bullfinch default
behavior is false which will return them same empty array is for success or
timeout on insert/delete/update statements 

# METHODS

## send( request_queue => $queue, request => \%data, response_queue_suffix => $response_name, process_by => $procby, expiration => $expire);

Send the request to the specified queue and await a response.  The data
should be a hashref and the queuename (optional) will be appended to
`response_prefix`.  This allows you to create a unique response queue per
request.

    # Response queue will be "response-net-kestrel-foobar"
    my $items = $client->send(\%data, "foobar");

Any messages sent in response (save the EOF message) are returned as an
arrayref to the caller.

The optional `process_by` must be an ISO 8601 date.

The optional `expiration` is the number of seconds this request should live
in the queue before expiring.

__Note:__ Send will die if it fails to properly enqueue the request.

# AUTHOR

Cory G Watson <gphat@cpan.org>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Infinity Interactive, Inc.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.