/ 
IPC-Manager-0.000035
/ IPC::Manager::Service

NAME

IPC::Manager::Service - Base class for creating IPC services

DESCRIPTION

This class provides a concrete implementation of the IPC::Manager::Role::Service role for creating IPC services. It handles message handling, peer management, signal handling, and the main event loop.

SYNOPSIS

use IPC::Manager::Service;

my $service = IPC::Manager::Service->new(
    name           => 'my-service',
    ipcm_info      => $ipcm_info,
    handle_request => sub {
        my ($self, $request, $msg) = @_;
        return {result => 'ok'};
    },
);

$service->run;

CONSTRUCTOR ARGUMENTS

name

The service name (required).

orig_io

Hashref with optional stdout and stderr filehandles for debug output.

ipcm_info

Connection information for the IPC system.

redirect

Boolean indicating whether to redirect I/O.

pid

The process ID.

use_posix_exit

Boolean indicating whether to use POSIX exit codes.

intercept_errors

Boolean indicating whether to intercept and log errors.

expose_error_details

Boolean indicating whether exception text from handle_request should be included verbatim in error responses. When false (the default), a generic "Internal service error" message is sent. When true, the stringified exception is sent as the ipcm_error value in the response.

watch_pids

Arrayref of PIDs to watch. If any terminates, the service exits.

interval

Interval for run_on_interval callbacks (default: 0.2 seconds).

cycle

Select cycle time (default: 0.2 seconds).

on_sig => {\%hash}

Hash of signal names to callback(s) for signal handling.

handle_request => \&callback

Callback for handling requests. Required unless on_all is provided.

handle_response => \&callback

Callback for handling responses. Defaults to confessing if not provided.

post_fork => \&callback

Callback called in the child process after ipcm_service forks but before the service takes over. Use this to implement a double-fork pattern: fork inside the callback, have the middle process do its work and exit, and let the grandchild return to become the service. The callback receives the service instance as its argument.

on_all => \&callback

Callback called for every activity cycle. If provided, handle_request and handle_response default to no-ops.

on_cleanup => \&callback

Callback called when the service is shutting down.

on_general_message => \&callback

Callback for messages that are not requests or responses.

on_interval => \&callback

Callback called at regular intervals.

on_peer_delta => \&callback

Callback called when peer connections change.

on_pid => \&callback

Callback called (with $pid and $exit) for each non-worker child process reaped by the service loop. Worker processes registered with ipcm_worker are handled internally and do not trigger this callback.

on_start => \&callback

Callback called on startup before the main loop.

on_unhandled => \&callback

Callback called when activity remains unhandled. Dies by default.

should_end => \&callback

Callback called to determine if the service should exit.

METHODS

@signal_names = $self->signals_to_grab()

Returns a list of signals to intercept.

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

Calls the configured request handler. The handler should return a single item (scalar, undef, reference) when if the response is ready. Should return an empty list if the request needs further processing.

$self->handle_response($resp, $msg)

Calls the configured response handler.

$self->clear_on_sig($sig)

Clears all handlers for a signal.

$self->push_on_sig($sig, $cb)

Adds a callback to the signal handlers.

$self->unshift_on_sig($sig, $cb)

Prepends a callback to the signal handlers.

$self->run_on_sig($sig, @args)

Runs all callbacks for a signal.

$self->remove_on_sig($sig, $cb)

Removes a specific callback from signal handlers.

$self->clear_on_all()

Clears the array of callbacks for on_all.

$self->push_on_all($cb)

Adds a callback to the on_all callback array.

$self->unshift_on_all($cb)

Prepends a callback to the on_all callback array.

$self->run_on_all(@args)

Runs all callbacks for on_all.

$self->remove_on_all($cb)

Removes a specific callback from the on_all callback array.

$self->clear_on_cleanup()

Clears the array of callbacks for on_cleanup.

$self->push_on_cleanup($cb)

Adds a callback to the on_cleanup callback array.

$self->unshift_on_cleanup($cb)

Prepends a callback to the on_cleanup callback array.

$self->run_on_cleanup(@args)

Runs all callbacks for on_cleanup.

$self->remove_on_cleanup($cb)

Removes a specific callback from the on_cleanup callback array.

$self->clear_on_general_message()

Clears the array of callbacks for on_general_message.

$self->push_on_general_message($cb)

Adds a callback to the on_general_message callback array.

$self->unshift_on_general_message($cb)

Prepends a callback to the on_general_message callback array.

$self->run_on_general_message(@args)

Runs all callbacks for on_general_message.

$self->remove_on_general_message($cb)

Removes a specific callback from the on_general_message callback array.

$self->clear_on_interval()

Clears the array of callbacks for on_interval.

$self->push_on_interval($cb)

Adds a callback to the on_interval callback array.

$self->unshift_on_interval($cb)

Prepends a callback to the on_interval callback array.

$self->run_on_interval(@args)

Runs all callbacks for on_interval.

$self->remove_on_interval($cb)

Removes a specific callback from the on_interval callback array.

$self->clear_on_peer_delta()

Clears the array of callbacks for on_peer_delta.

$self->push_on_peer_delta($cb)

Adds a callback to the on_peer_delta callback array.

$self->unshift_on_peer_delta($cb)

Prepends a callback to the on_peer_delta callback array.

$self->run_on_peer_delta(@args)

Runs all callbacks for on_peer_delta.

$self->remove_on_peer_delta($cb)

Removes a specific callback from the on_peer_delta callback array.

$self->clear_on_pid()

Clears the array of callbacks for on_pid.

$self->push_on_pid($cb)

Adds a callback to the on_pid callback array.

$self->unshift_on_pid($cb)

Prepends a callback to the on_pid callback array.

$self->run_on_pid($pid, $exit)

Runs all callbacks for on_pid, passing the reaped child's PID and raw $? exit value.

$self->remove_on_pid($cb)

Removes a specific callback from the on_pid callback array.

$self->clear_on_start()

Clears the array of callbacks for on_start.

$self->push_on_start($cb)

Adds a callback to the on_start callback array.

$self->unshift_on_start($cb)

Prepends a callback to the on_start callback array.

$self->run_on_start(@args)

Runs all callbacks for on_start.

$self->remove_on_start($cb)

Removes a specific callback from the on_start callback array.

$self->clear_on_unhandled()

Clears the array of callbacks for on_unhandled.

$self->push_on_unhandled($cb)

Adds a callback to the on_unhandled callback array.

$self->unshift_on_unhandled($cb)

Prepends a callback to the on_unhandled callback array.

$self->run_on_unhandled(@args)

Runs all callbacks for on_unhandled.

$self->remove_on_unhandled($cb)

Removes a specific callback from the on_unhandled callback array.

$self->clear_should_end()

Clears the array of callbacks for should_end.

$self->push_should_end($cb)

Adds a callback to the should_end callback array.

$self->unshift_should_end($cb)

Prepends a callback to the should_end callback array.

$self->run_should_end(@args)

Runs all callbacks for should_end. Returns true if any callback returns true.

$self->remove_should_end($cb)

Removes a specific callback from the should_end callback array.

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/