NAME

IPC::Manager::Client - Base class for all client protocols

DESCRIPTION

All connections should be a subclass of this class. This interface describes all the common methods provided by all protocols.

SYNOPSIS

my $con = IPC::Manager::Client::[PROTOCOL]->new($client_name, $serializer_class, $route);

$con->send_message($peer_name => {hello => 'world'});

for my $msg ($con->get_messages) {
    handle_message($msg);
}

$con->disconnect;

METHODS

CLASS METHODS

($route, $stash) = IPC::Manager::Client::[PROTOCOL]->spawn(serializer => $SERIALIZER, %params)

Used to vivify a completely new message store for the given protocol.

IPC::Manager::Client::[PROTOCOL]->unspawn($route, $stash)

Used to destroy the previously created message store.

$con = IPC::Manager::Client::[PROTOCOL]->connect($client_name, $serializer, $route)

Establish a connection with a message store.

$con = IPC::Manager::Client::[PROTOCOL]->reconnect($client_name, $serializer, $route)

Re-establish a suspended connection.

Note: This is not possible with some protocols, mainly 'UnixSocket'.

@clients = $con->local_clients($route)

This will return a reference to every active client for the specified route that was established in the current process.

This is mainly used to disconnect clients in this process before waiting for all clients to exit, avoiding a deadlock.

INSTANCE METHODS

$stats = $con->all_stats

Get all stats for all connections.

Note: This is not useful until all connections have disconnected as stats are not written until disconnect.

$con->broadcast($message)

$con->broadcast($message_content)

$con->broadcast(%message_fields)

Send a message to all peers. Can be an IPC::Manager::Message instance, contents of a message, or a list of fields and values for the message (contructor arguments).

$msg = $con->build_message($message_obj)

$msg = $con->build_message($message_obj, %overrides)

$msg = $con->build_message($peer, $message_content)

$msg = $con->build_message($peer, $message_content, %message_fields)

$msg = $con->build_message(to => $peer, content => $message_content, %other_fields)

Construct a message from various possible argument forms. This is used by send_message() and try_message().

$con->disconnect

Sub terminate the connection.

$con->disconnected

Check if the connection has been terminated.

@messages = $con->get_messages()

Get all currently ready messages. Each message will be an instance of IPC::Manager::Message. All message info will already be deserialized for you.

$bool = $con->have_pending_messages

True if there are messages still incoming and the protocol can detect that. For many protocols this will always return 0.

$bool = $con->have_ready_messages

True if there are messages ready for reading.

$client_name = $con->id

Get the identifier for this connection.

$bool = $con->peer_active($peer_name)

Check if the specified peer is active.

$bool = $con->peer_exists($peer_name)

Check if the specified peer exists, even if it is suspended.

$pid = $con->peer_pid($peer_name)

Get the pid of a peer, undef if it does not exist or is not running.

@peer_names = $con->peers()

Get the names of all peers.

$pid = $con->pid

Get the PID for this connection.

$con = $con->pid_check

Returns the connection object if the current PID matches the connection PID. Throws an exception if used from the wrong PID.

$state = $con->pid_is_running($pid)

Check if a PID is running.

Returns 1 if the process is running, 0 if it is not running, and -1 if it is running but we have no permissions to send signals to it.

$con->post_disconnect_hook

Used by subclasses to add disconnect behaviors before disconnect.

$con->post_suspend_hook

Used by subclasses to add disconnect behaviors before suspend.

$con->pre_disconnect_hook

Used by subclasses to add disconnect behaviors after disconnect.

$con->pre_suspend_hook

Used by subclasses to add disconnect behaviors after suspend.

$hashref = $con->read_stats()

Read the connections stats (messages sent and recieved). This will only work after either a disconnect or a call to $con->write_stats.

$con->requeue_message($msg)

Put a message back in the queue. This is useful if the process needs to exec, or be re-started before the message can be handled.

$rourte = $con->route

Get the route info for the message store.

$con->send_message($message_obj)

$con->send_message($message_obj, %overrides)

$con->send_message($peer, $message_content)

$con->send_message($peer, $message_content, %message_fields)

$con->send_message(to => $peer, content => $message_content, %other_fields)

Takes all the same argument options as build_message().

Will send a message, and will throw an exception if it is unable to send. Success only guarentees that the message was written, not that the peer reads it.

$serializer_class = $con->serializer

Get the serializer class used for the connection.

$hashref = $con->stats

Get the message stats (sent and recieved counts).

$con->suspend

Used to disconnect with intent to reconnect, which means peers can still send messages to this connection while it is offline. Some protocols, like UnixSocket do not support this.

$bool = $con->try_message($message_obj)

($bool, $err) = $con->try_message($message_obj)

$bool = $con->try_message($message_obj, %overrides)

($bool, $err) = $con->try_message($message_obj, %overrides)

$bool = $con->try_message($peer, $message_content)

($bool, $err) = $con->try_message($peer, $message_content)

$bool = $con->try_message($peer, $message_content, %message_fields)

($bool, $err) = $con->try_message($peer, $message_content, %message_fields)

$bool = $con->try_message(to => $peer, content => $message_content, %other_fields)

($bool, $err) = $con->try_message(to => $peer, content => $message_content, %other_fields)

Attempt to send a message. In list context it will return a boolean, and if the boolean is false it will also return the error message. In scalar context it returns a boolean and if it is false it sets $@ to the error message.

$con->write_stats

Write the $con->stats data to the data store so that $con->read_stats can read it.

$bool = $con->viable

Returns true if this protocol is usable in the current environment, i.e. all required modules are loadable and any runtime prerequisites (kernel features, available file types, etc.) are satisfied. Always check viable before calling spawn with a protocol you have not explicitly required.

This method is provided by the base class and is guaranteed never to throw an exception. Subclasses should not override viable directly; instead they must implement _viable, which should either return a true value or throw an exception explaining why the protocol is not available. The base-class viable calls _viable inside an eval and translates any exception into a false return.

$bool = $con->have_handles_for_select

Returns true if this client provides filehandles that can be passed to IO::Select to wait for incoming messages. Returns false by default; protocols that support it override this to return true.

@handles = $con->handles_for_select

Returns the list of filehandles to register with IO::Select for incoming message notification. Only valid when have_handles_for_select returns true.

$bool = $con->have_handles_for_peer_change

Returns true if this client can supply a filehandle that becomes readable whenever the set of connected peers changes (e.g. a new client connects or an existing one disconnects). Returns false by default.

$con->reset_handles_for_peer_change

Drains or resets the peer-change notification handle after a peer-change event has been processed, so that it does not remain spuriously readable. Only valid when have_handles_for_peer_change returns true.

@handles = $con->handles_for_peer_change

Returns the filehandle(s) that become readable on a peer-connect or peer-disconnect event. Only valid when have_handles_for_peer_change returns true.

SOURCE

The source code repository for IPC::Manager can be found at https://github.com/exodist/IPC-Manager.

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright Chad Granum <exodist7@gmail.com>.

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

See https://dev.perl.org/licenses/