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

NAME

IPC::Manager::Service::Handle - Handle class for connecting to IPC services

DESCRIPTION

This class provides a client-side handle for connecting to IPC services. It manages the connection to a service and provides methods for sending requests and receiving responses.

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

SYNOPSIS

my $handle = IPC::Manager::Service::Handle->new(
    service_name => 'my-service',
    ipcm_info    => $ipcm_info,
);

# Send a synchronous request
my $response = $handle->sync_request({action => 'do_something'});

# Poll for messages
$handle->poll;

# Get buffered messages
my @messages = $handle->messages;

ATTRIBUTES

service_name

The name of the service to connect to (required).

name

The name of this handle connection (optional, defaults to a UUID).

ipcm_info

Connection information for the IPC system (required).

interval

Polling interval in seconds (default: 0.2).

client

The underlying client connection (internal use).

request_callbacks

Hash of request callbacks (internal use).

requests

Hash of pending requests (internal use).

buffer

Array of received messages (internal use).

METHODS

@file_handles = $self->select_handles()

Returns a list of filehandles for select().

$bool = $self->ready()
$bool = $self->ready($timeout)

Returns true if the handle's peer service is active.

With no argument (or undef), ready returns the current state immediately (one-shot, backwards-compatible).

With $timeout, ready blocks until the peer becomes active or the timeout elapses, whichever comes first. A $timeout of 0 blocks indefinitely.

Uses the underlying client's peer-change notification handle (IO::Select on an inotify/similar fd) where available; otherwise falls back to a short sub-second sleep-and-retry loop.

$client = $self->client()

Returns the client connection, creating it if necessary.

$pid = $self->service_pid()

Returns the PID of the peer service.

$pid = $self->child_pid()

Returns the pid that fork returned in ipcm_service's parent branch (the "first-fork" pid). Populated only when the handle was produced by ipcm_service spawning a child; undef otherwise (e.g. on handles constructed directly via IPC::Manager->connect).

Caveat: this is ipcm_service's own fork pid, not necessarily the pid the service loop ends up running in. If a post_fork_hook daemonizes (double-fork + parent-exit), the first-fork pid exits inside the hook and this value becomes stale; use service_pid to retrieve the currently running service pid in that case. If a post_fork_hook interposes a long-lived wrapper (parent becomes the wrapper, child runs the service loop), child_pid is the wrapper pid and is the correct pid for a supervisor to watch.

$res = $self->sync_request($peer, $payload)
$res = $self->sync_request($peer, $payload, $timeout)

Sends a request and waits for the response. Returns the response.

If $timeout (seconds) is provided, sync_request will croak with a timeout message if no response arrives before the deadline. If $timeout is omitted or undef, the call blocks indefinitely.

Regardless of the timeout, sync_request will also croak if the target peer is fully removed from the bus while the request is outstanding.

For protocols that support suspend/reconnect (see suspend_supported in IPC::Manager::Client), a peer that has merely suspended or restarted under a new process id is not treated as gone: the call keeps waiting, because a response can still arrive once the peer resumes. Only full unregistration (peer_exists false) triggers the peer-went-away error. For protocols without suspend support, a dead process id counts as gone.

$res = $self->await_response($id)
$res = $self->await_response($id, $timeout)

Waits for a response to a request. Returns the response when available.

Honors the same $timeout and peer-death semantics as sync_request.

$self->await_all_responses()
$self->await_all_responses($timeout)

Waits for all pending responses to arrive. If $timeout is provided, throws after that many seconds with pending responses still outstanding.

Honors the same peer-death semantics as await_response: if any pending peer goes away (after a final drain) before its response arrives, this throws "peer(s) '...' went away while awaiting responses".

@messages = $self->messages()

Returns and clears the message buffer.

$self->poll()
$self->poll($timeout)

Polls for messages. Returns the number of messages received.

If $timeout is provided, waits up to that many seconds for messages.

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/