NAME

Async::Blackboard - A simple blackboard database and dispatcher.

SYNOPSIS

my $blackboard = Async::Blackboard->new();

$blackboard->watch([qw( foo bar )], [ $object, "found_foobar" ]);
$blackboard->watch(foo => [ $object, "found_foo" ]);

$blackboard->put(foo => "First dispatch");
# $object->found_foo("First dispatch") is called
$blackboard->put(bar => "Second dispatch");
# $object->found_foobar("First dispatch", "Second dispatch") is called

$blackboard->clear;

$blackboard->put(bar => "Future Dispatch");
# No dispatch is called...
# but $blackboard->get("bar") eq "Future Dispatch"

$blackboard->put(foo => "Another dispatch");

# Order of the following is undefined:
#
# $object->found_foo("Future dispatch") is called
# $object->found_foobar("Future Dispatch", "Another dispatch") is called

$blackboard->hangup;

RATIONALE

Concurrent applications can often do one or more thing at a time while "waiting" for a response from a given service. Conversely, sometimes applications cannot dispatch all requests until certain data elements are present, some of which may require lookups from other services. Maintaining these data-dependencices in a decentralized fashion can eventually lead to disparity in the control of a workflow, and possibly missed opportunities for optimizing parallelism. This module attempts to address this design issue by allowing the data dependencies and subsequent workflow to be descriptively defined in a central place.

ATTRIBUTES

CONSTRUCTORS

Async::Blackboard includes a static builder method for constructing prototype blackboards using concise syntax. The is should typically be used whenever describing a workflow in detail prior to use (and then cloning the blackboard) is the desired usecase.

build watchers => [ ... ]

build values => [ ... ]

build watchers => [ ... ], values => [ ... ]

Build and return a blackboard prototype, it takes a balanced list of keys and array references, with the keys specifying the method to call and the array reference specifying the argument list. This is a convenience method which is short hand explained by the following example:

my $blackboard = Async::Blackboard->new();

$blackboard->watch(@$watchers);
$blackboard->put(@$values);

# This is equivalent to
my $blackboard = Async::Blackboard->build(
    watchers => $watchers,
    values   => $values
);

METHODS

has KEY

Returns true if the blackboard has a value for the given key, false otherwise.

watch KEYS, WATCHER

watch KEY, WATCHER

Given an array ref of keys (or a single key as a string) and an array ref describing a watcher, register the watcher for a dispatch when the given data elements are provided. The watcher may be either an array reference to a tuple of [ $object, $method_name ] or a subroutine reference.

In the instance that a value has already been provided for this key, the dispatch will happen immediately.

Returns a reference to self so the builder pattern can be used.

watcher KEY

watcher KEYS

Given a key or an array reference of keys, return all watchers interested in the given key.

found KEY

Notify any watchers of a key that it has been found, if all of their other _interests have been found. This method is usually not invoked by the client.

put KEY, VALUE [, KEY, VALUE .. ]

Put the given keys in the blackboard and notify all watchers of those keys that the objects have been found, if and only if the value has not already been placed in the blackboard.

The `found` method is invoked for each key, as the key is added to the blackboard.

weaken KEY

Weaken the reference to KEY.

When the value placed on the blackboard should *not* have a strong reference (for instance, a circular reference to the blackboard), use this method to weaken the value reference to the value associated with the key.

delete KEY [, KEY ...]

Given a list of keys, remove them from the blackboard. This method should be used with caution, since watchers are not notified that the values are removed but they will be re-notified when a new value is provided.

replace KEY, VALUE [, KEY, VALUE .. ]

Given a list of key value pairs, replace those values on the blackboard. Replacements have special semantics, unlike calling `remove` and `put` on a single key in succession, calling `replace` will not notify any watchers of the given keys on this blackboard. But watchers waiting for more than one key who have not yet been notified, will get the newer value. Further, replace will dispatch the found event if the key is new.

get KEY [, KEY .. ]

Fetch the value of a key. If given a list of keys and in list context, return the value of each key supplied as a list.

clear

Clear the blackboard of all values.

hangup

Clear all watchers, and stop accepting new values on the blackboard.

Once hangup has been called, the blackboard workflow is finished.

watched

Return a list of all keys currently being watched.

clone

Create a clone of this blackboard. This will not dispatch any events, even if the blackboard is prepopulated.

BUGS

None known.

LICENSE

Copyright © 2011, Say Media. Distributed under the Artistic License, 2.0.