Documentation | ApplicationKit | Messenger

SYNOPSIS

use HaikuR1::Messenger;

my $messenger = HaikuR1::Messenger->new($handler, $looper);
$messenger->SendMessage($message);

from HaikuR1.ApplicationKit import Messenger

messenger = Messenger(handler, looper)
messenger.SendMessage(message)

DESCRIPTION

Exposes the BMessenger object.

For more information on Messenger, see the Be Book class description, the Be Book overview, and the Haiku Book class description.

METHODS

Constructor

Creates an Messenger with a local target.

HaikuR1::Messenger->new($param1, $param2);

Messenger(param1, param2)

• param1

  Optional; either a Messenger to copy or a Handler in the local team or a native string containing the signature of a running app.

• param2

  Optional; either a Looper (when param1 is a Handler) or an integer team id (when param1 is a signature).

To target a Looper directly, pass it as param1 (this works because a Looper is also a Handler). To target a Looper's preferred handler, pass the empty value as param1 and the Looper as param2.

If you pass a signature without a team, you target a running team with that signature (assuming such an instance is actually running). If you pass a signature and a team, you will get a valid Messenger only if that team has that signature. If you pass the empty value as param1 and a valid team id as param2, you will target that team no matter what it's signature.

copy

Copies the contents of another object into this object.

$messenger->copy($copy_from);

messenger.copy(copy_from)

• copy_from

A Messenger to copy.

IsTargetLocal

Returns true if the target is local, false if it is remote or if the Messenger is not valid.

$messenger->IsTargetLocal();

messenger.IsTargetLocal()

HashValue

Returns a value that is the same if the targets are the same and (probably) different if the targets are different.

$messenger->HashValue();

messenger.HashValue()

IsValid

Returns true if the Messenger is valid.

$messenger->IsValid();

messenger.IsValid()

Locking

LockTarget

LockTargetWithTimeout

These methods do what you would expect. They work only on local targets.

LockTarget will block until it obtains a lock. LockTargetWithTimeout may signal an error.

Note that there is no UnlockTarget method.

Locks the target looper (if it is local).

$messenger->LockTarget();
$messenger->LockTargetWithTimeout($timeout);

messenger.LockTarget()
messenger.LockTargetWithTimeout(timeout)

• timeout

  An integer, timeout in microseconds.

SendMessage

Sends a Message to the target. Signals an error on failure.

$messenger->SendMessage(
    message => $message,
    replyTo => $replyTo,
    timeout => $timeout,
    replyTimeout => $replyTimeout,
    synchronous => $synchronous,
);

messenger.SendMessage(
    message = message,
    replyTo = replyTo,
    timeout = timeout,
    replyTimeout = replyTimeout,
    synchronous = synchronous,
)

• message

  A Message or an integer; if an integer, a it will be used to create a Message internally.

• replyTo

  Optional; a Handler or a Messenger that any reply to this message will be sent to.

• timeout

  Optional; an integer that specifies a timeout for sending this message; defaults to B_INFINITE_TIMEOUT.

• replyTimeout

  Optional; an integer that specifies a timeout for reciving a reply to this message; defaults to B_INFINITE_TIMEOUT.

• synchronous

  Optional; an boolean that specifies whether the call should be synchronous (waits for a reply to this message) or asynchronous (returns once it has successfully sent this message); defaults to false (asynchronous call).

  This option will be ignored if replyTo is specified; specifying a reply target always results in an asynchronous call.

SetTo

Sets the Messenger to a local target. Signals an error on failure.

$messenger->SetTo($handler, $looper);

messenger.SetTo(handler, looper)

• param1

  Optional; either a Handler in the local team or a native string containing the signature of a running app.

• param2

  Optional; either a Looper (when param1 is a Handler) or an integer team id (when param1 is a signature).

The parameters have the same effect as for the constructor. (Note: you cannot pass a Messenger as param1, unlike with new.)

Target

Returns the handler and looper that are a local target.

$messenger->Target();

messenger.Target()

Team

Returns the id of the target team, or signals an error.

$messenger->Team();

messenger.Team()

OPERATORS

==

Returns true if the Messengers have the same target.

!=

Returns true if the Messengers have different targets.

<

Applies a consistent ordering to Messengers; mainly used internally.