Table of Contents

Class: Dispatch ./src/peak/util/dispatch.py

Mapping from rules to objects (slow, but simple)

This is a generic rule-driven lookup table that finds the "closest matches" based on whether a supplied key matches rules in the table, returning results for the most-specific rules first. It can be used to implement business rules, stylesheets, generic functions, multimethods, or anything else you can think of that needs prioritized rule-driven matching. All you need are objects that implement the IRule interface to act as rules, and the Dispatch class automatically handles issues like overlapping rules.

Note that Dispatch objects are "write until read", so once you use a dispatch table to process an object, you can no longer change its rules.

Usage:

        # Dispatcher that doesn't hold references to looked-up objects
        dispatcher = Dispatch(WeakKeyDictionary())
        dispatcher[aBusinesRule] = actionToTake

        # Retrieve action for closest match -- error if none found or ambiguous
        actionToTake = dispatcher[aBusinessObject].next()

Performance

The principal drawback of this class is speed. Although lookups are cached, each new uncached lookup requires a loop over all the rules in the table, with each rule being asked to match the key being looked up. Then, the matching rules are sorted to put them in "closest-match-first" order, and this uses many function calls per comparison.

However, for many simple applications of rule-based dispatching (such as multiple-dispatch of generic functions), where there aren't too many rules and even fewer that match on any given lookup, performance should be acceptable. For more complex applications, you'll want a more sophisticated dispatcher that has internal indexes for its rules. But, you can always use this dispatcher as a prototype to get the rest of your system figured out first.

Base Classes   
object
Methods   
__getitem__
__init__
__setitem__
  __getitem__ 
__getitem__ ( self,  key )

Return an iterator over the results for rules matching key

Raises NoMatchError if no rules match key. The iterator will raise AmbiguousRulesError if it is advanced to a point where match precedence is ambiguous. This may be as early as the very first match, if there is no match which is unambiguously "closest" to key.

Exceptions   
NoMatchError( "No match found", key )
  __init__ 
__init__ (
        self,
        items=(),
        cache=None,
        )

Create dispatcher from items, optionally supplying a lookup cache

The default cache type for Dispatch objects is a dictionary, so all values looked up are cached permanently - not a good idea for many applications. You can change this by supplying a cache object of your choice. The cache must provide __getitem__ and __setitem__ methods.

The items parameter, if supplied, should be a sequence of (rule,result) tuples to initially populate the dispatcher.

  __setitem__ 
__setitem__ (
        self,
        rule,
        result,
        )

Store result as output for rule


Table of Contents

This document was automatically generated on Tue Feb 17 19:55:52 2004 by HappyDoc version 2.1