[PEAK] The Trellis has landed

[Phillip J. Eby]

The new algorithm is now in SVN, as Trellis-0.6a1dev-r2436, if you'd 
like to experiment.

The documentation is practically untouched from the old version, and 
is thus out-of-date and *materially misleading*.  The code examples 
of course work, but you can't trust the explanatory text.  And there 
are important APIs that aren't documented at all.

In practice, however, most existing trellis code should only need two 
kinds of changes:

* @action rules should switch to @rule, @observer, or a combination of the two

* Tasks can no longer observe discrete or receiver cells, and require 
an active EventLoop to run

When converting @action rules, you must separate your code into code 
that makes trellis changes, and code that does non-trellis things 
(like GUI updates, I/O, etc.).  The former should become @rule, and 
the latter should become @observer.

The only exception is when you have an @action that really intends 
that its changes should take effect in the *future*, instead of in 
the current recalculation.  If you intend your changes to take place 
in the future, you should use a @task or EventLoop.call() to schedule them.

Also, note that rules can now be run more than once during the same 
recalculation pass -- if your rule has side-effects (other than 
setting cell values, or using trellisized data structures) it *must* 
use trellis.on_undo(func, *args) to register undo functions to be 
called in the event of an error or the need to recalculate due to an 
out-of-order modification.

And speaking of undo and trellis data structures, please note that 
Dict, List, and Set do not actually support undo yet, which means 
they're not safe for modification via rules at the present 
moment.  I'll be fixing this soon, I hope, but in the meantime, 
please be aware of it.

By the way, if you'd like to see a cool wxPython demo app built on 
the Trellis, take a look at:

http://svn.osafoundation.org/chandler/branches/rearchitecture/

It's an experimental and in-progress refactoring of the Chandler 
application UI to run on the Trellis and other PEAK technology such 
as AddOns, PlugIns, etc.

In order to actually run it, you'll need to install this first, though:

http://svn.osafoundation.org/chandler/trunk/chandler/

as we're using Chandler's custom wx, PyICU, and various other 
libraries including Twisted.

(Oh, and yes, it works with the new Trellis algorithm.)