/ 
IPC-Manager-0.000006
River stage zero No dependents
/ IPC::Manager::Role::Service

NAME

IPC::Manager::Role::Service - Role for implementing IPC services with message handling

DESCRIPTION

This role provides the core functionality for IPC services including:

Message handling (requests/responses)
Peer management and delta detection
Signal handling
Worker process management
Main event loop via the run() method

It composes with IPC::Manager::Role::Service::Select and IPC::Manager::Role::Service::Requests for I/O multiplexing and request/response patterns.

SYNOPSIS

package MyService;
use Role::Tiny::With;
with 'IPC::Manager::Role::Service';

sub new { ... }

sub orig_io { ... }

sub name { ... }

sub run { ... }

sub ipcm_info { ... }

sub pid { ... }

sub set_pid { ... }

sub watch_pids { ... }

sub handle_request { ... }

1;

REQUIRED METHODS

These methods must be implemented by the consuming class:

$inst = $class->new(%params)

Constructor. Must accept parameters for initialization.

$io = $self->orig_io()

Returns a hashref with optional stdout, stderr, or stdin filehandles.

$string = $self->name()

Returns the service name.

$exit = $self->run()

Runs the main event loop. Returns when the service is terminated. Should return an exit code.

$info = $self->ipcm_info()

Returns connection information for the IPC system.

$pid = $self->pid()

Returns the process ID the service is supposed to be confined to.

$self->set_pid($pid)

Sets the process ID (used after fork).

$pids_arrayref = $self->watch_pids()

Returns an arrayref of PIDs to watch. If any terminates, the service exits.

($resp) = $self->handle_request($request, $msg)

Handles an incoming request message.

Should return an empty list if the request is being processed, but no response is ready.

Should return a single item (undef, scalar, or reference) for a response.

If this returns multiple items an exception will be thrown.

METHODS

$self->cycle()

Returns the select cycle time (default: 0.2 seconds).

$self->interval()

Returns the interval for run_on_interval callbacks (default: 0.2 seconds).

$self->use_posix_exit()

Returns whether to use POSIX exit codes (default: 0).

$self->intercept_errors()

Returns whether to intercept and log errors (default: 0).

$val = $self->terminated()

Gets the termination status.

$self->is_terminated()

Returns true if the service is terminated.

$val = $self->terminate()
$val = $self->terminate($val)

Sets the termination status. If no value is provided then 0 is used. Returns the new value.

$class = $self->peer_class()

Returns the class to use for peer connections (default: IPC::Manager::Service::Peer).

$class = $self->handle_class()

Returns the class to use for handles (default: IPC::Manager::Service::Handle).

@signal_names = $self->signals_to_grab()

Returns a list of signals to intercept (default: empty).

$self->redirect()

Override to redirect I/O. Called during startup. Default implementation is a no-op.

$self->pre_fork_hook()

Override to run code before forking workers. Default implementation is a no-op.

$self->run_on_all($activity)

Called for every iteration of the service's main loop.

See the "ACTIVITY HASH" for a description of the $activity input.

$self->run_on_cleanup()

Called when the service is shutting down.

$self->run_on_general_message($msg)

Called for messages that are not requests or responses.

$self->run_on_interval()

Called at regular intervals (controlled by interval()).

$self->run_on_peer_delta($delta)

Called when peer connections change. $delta is a hashref showing added/removed peers.

The "ACTIVITY HASH" section shows the structure of the peer_delta as well.

$self->run_on_sig($sig)

Called when a signal is received. May be called multiple times in rapid succession in a single loop iteration if a signal is recieved more than once.

$self->run_on_start()

Called on startup before the main loop.

$self->run_should_end()

Called to determine if the service should exit. Return true to terminate.

$self->run_on_unhandled($activity)

Called when activity remains unhandled after processing. Dies by default.

See the "ACTIVITY HASH" for a description of the $activity input.

$self->clear_service_fields()

Clears all internal state fields.

$self->register_worker($name, $pid)

Registers a worker process.

$self->workers()

Returns a hashref of worker PIDs to names.

$self->reap_workers()

Reaps terminated worker processes. Returns a hashref of results.

$self->send_response($peer, $id, $resp)

Sends a response message to a peer.

$client = $self->client()

Returns the client connection for this service.

$self->in_correct_pid()

Verifies we're running in the correct process. Dies if not.

$self->kill($sig)

Sends a signal to the service process.

$self->debug(@msg)

Outputs debug messages to the appropriate filehandle.

$self->handle(name => $name, %params)

Creates a new handle for connecting to this service.

$self->peer($name, %params)

Creates a peer connection to another service.

$res = $self->try($cb)

Executes a callback with optional error interception.

$res is a hashref:

{
    ok => $bool,
    err => $string,
    out => ...,
}
$delta = $self->peer_delta(%params)

Returns a hashref showing changes in peer connections.

@handles = $self->select_handles()

Returns a list of filehandles for select().

$activity = $self->watch($sig_seen)

Waits for activity and returns an activity hashref.

See the "ACTIVITY HASH" for a description of the $activity output.

$terminated = $self->run()

Runs the main event loop until terminated. Returns the termination value.

ACTIVITY HASH

The methods that take an activity hash get this structure:

Note that all keys that are not applicable may be omitted.

{
    # Set if the time interval has passed since the last iteration
    interval => $bool,

    # An arrayref of messages, if any
    messages => \@messages,

    # A hashref for peers that have been added or removed, -1 means removed, 1 means added.
    peer_delta => {peer1 => -1, peer3 => 1},

    # True if a wtached pid has exited
    pid_watch => $bool,

    # Hashref of all signals intercepted since the last iteration, plus a count of how many times they were recieved
    sigs => {sig => $count, sig2 => $count2},

    # Set if termination has occured, along with the termination value as a key on the hashref.
    terminated => { value => $value },
}

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/