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, but both are called:
  #
  # $object->found_foo("Future dispatch")
  # $object->found_foobar("Future Dispatch", "Another dispatch")

  $blackboard->hangup;

DESCRIPTION

Async::Blackboard provides a mechanism for describing the a parallizable workflow as a series of merge points. An instance of a given workflow is associated with a blackboard, which might be cloned from a prototype blackboard. The blackboard is a key value store which contains the data necessary to complete the task in question.

The description of the workflow is in the form of a type of event listener, which is notified when values are associated with a given set of keys. Once values have been published to the blackboard for all of the keys a given listener is interested in, the listener is invoked given the values. That listener then has the opportunity to provide more values. Used in an asynchornous I/O bound application, this allows the application workflow to be intrinsically optimized for parallelism.

CONSTRUCTORS

new

The new constructor takes no arguments. If you wish to initialize a blackboard which is prepopulated, try using the ``build'' constructor, or cloning a blackboard in a partially run state using the ``clone'' method.

This is done to maintain the guarantee that each listener is notifed once and only once upon its dependencies being satisifed.

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

hungup

Determine whether or not the blackboard has been hung up. A blackboard which has been hung up will stop accepting values and release all watcher references.

has KEY

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

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.

watcher KEY

watcher KEYS

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

watched

Return a list of all keys currently being watched.

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.

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.

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.

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.

clone

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

The clone is two levels, and the two blackboards will operate independently of one another, but any references stored as values on the blackboard will be shared between the two instances.

BUGS

None known, but please submit them to https://github.com/ssmccoy/Async-Blackboard/issues if any are found, or CPAN RT.

LICENSE

Copyright (C) 2011, 2012, 2013 Say Media.

Distributed under the Artistic License, 2.0.