view release on metacpan or  search on metacpan

lib/AnyEvent/RabbitMQ/RPC.pm  view on Meta::CPAN

C<vhost>.

If you wish to pass complex data structures back and forth to remote
workers, a value must be passed for C<serialize>.  Both worker and
client must be configured to use the same serialization method.  The
available options are:

=over

=item YAML

Use L<YAML::Any/Dump> and L<YAML::Any/Load> to serialize and deserialize
data.

=item JSON

Use L<JSON::Any/objToJson> and L<JSON::Any/jsonToObj> to serialize and
deserialize.

=item Storable

Use L<Storable/nfreeze> and L<Storable/thaw> to serialize and
deserialize.

=back

Two callback points, C<on_success> and C<on_failure>, are provided.
C<on_success> will be passed the initialized L<AnyEvent::RabbitMQ::RPC>
object; C<on_failure> will be passed the reason for the failure.  If no
C<on_success> is provided, this call will block using an
L<AnyEvent::CondVar> until the connection is established.


=head2 register name => C<STRING>, run => C<SUBREF>

Establishes that the current process knows how to run the job named
C<STRING>, whose definition is provided by the surboutine C<SUBREF>.
The subroutine will be called whenever a job is removed from the queue;
it will be called with the argument passed to C</call>, which may be
more than a string if C<serialize> was set during L</new>.

Due to a limitation of C<AnyEvent::RabbitMQ>, false values returned by
the subroutine are transformed into the true-valued string C<0E0>.
Subroutines which fail to execute to completion (via C<die> or other
runtime execution failure) will re-insert the job into the queue for the
next worker to process.

Returning non-string values requires that both worker and client have
been created with the same (non-empty) value of C<serialize> passed to
L</new>.

A callback C<on_failure> may optionally be passed, which will be called
with an error message if suitable channels cannoot be configured on the
RabbitMQ server.

=head2 call name => C<STRING>, args => C<VALUE>

Submits a job to the job queue.  The C<VALUE> provided must be a string,
unless C<serialize> was passed to L</new>.

Three callbacks exist:

=over

=item on_reply

Called when the job has been completed successfully, and will be passed
the return value of the job.  Returning non-string values requires that
both worker and client have been created with the same (non-empty) value
of C<serialize> passed to L</new>.

=item on_sent

Called once the job has been submitted, with a true value if the job was
submitted successfully.  A false value will be passed if the requisite
channels could not be configured, and the job was not submitted
sucessfully.

=item on_failure

Called if there was an error submitting the job, and is passed the
reason for the failure.  If C<on_sent> was also provided, this is
I<also> called after C<on_sent> is called with a false value.

=back


If no value for C<on_reply> is provided, and the C<call> function is not
in void context, a C<AnyEvent::CondVar> is used to automatically block
until a reply is received from a worker; the return value of the reply
is then returned from L</call>.


=head2 connection

Returns the L<AnyEvent::RabbitMQ> connection used by this object.

=head2 channel

Returns the L<AnyEvent::RabbitMQ::Channel> used by this object.

=head2 rpc_queue queue => C<NAME>, on_success => C<CALLBACK>

Creates the queue with the given name, used to schedule jobs.  These
queues are durable, and thus persist across program invocations and
RabbitMQ restarts.

The C<on_success> callback is called once the queue is known to exist.
The C<on_failure> may alternately be called with a reason if the queue
creation fails.

=head2 reply_queue on_success => C<CALLBACK>

Creates a temporary queue used to reply to job requests.  These queues
are anonymous and ephemeral, and are torn down after each RPC call.

The C<on_success> callback is called with the name of the queue that has
been created.  The C<on_failure> may alternately be called with a reason
if the queue creation fails.