NAME

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

SYNOPSIS

  my $blackboard = AnyEvent::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.

The _objects present in this blackboard instance.

A hash reference of callbacks for each watcher, with the key for the watcher as its key.

A hash table with which has each watcher as a key, and array reference to an array of interested keys as a value.

The hangup flag.

default_timeout -> Num

Default timeout in (optionally fractional) seconds.

CONSTRUCTORS

AnyEvent::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 = AnyEvent::Blackboard->new();

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

    # This is equivalent to
    my $blackboard = AnyEvent::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.

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.

timeout SECONDS, [ KEY, [, DEFAULT ] ]

Set a timer for N seconds to provide "default" value as a value, defaults to `undef`. This can be used to ensure that blackboard workflows do not reach a dead-end if a required value is difficult to obtain.

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.

BUGS

None known.

LICENSE

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