Values

The core Value class is an internal part of circuits’ Futures and Promises used to fulfill promises of the return value of an event handler and any associated chains of events and event handlers.

Basically when you fire an event foo() such as:

x = self.fire(foo())

x here is an instance of the Value class which will contain the value returned by the event handler for foo in the .value property.

Note

There is also getValue() which can be used to also retrieve the underlying value held in the instance of the Value class but you should not need to use this as the .value property takes care of this for you.

The only other API you may need in your application is the notify which can be used to trigger a value_changed event when the underlying Value of the event handler has changed. In this way you can do something asynchronously with the event handler’s return value no matter when it finishes.

Example Code:

 1#!/usr/bin/python -i
 2
 3
 4from circuits import handler, Event, Component, Debugger
 5
 6
 7class hello(Event):
 8    "hello Event"
 9
10
11class test(Event):
12    "test Event"
13
14
15class App(Component):
16
17    def hello(self):
18        return "Hello World!"
19
20    def test(self):
21        return self.fire(hello())
22
23    @handler("hello_value_changed")
24    def _on_hello_value_changed(self, value):
25        print("hello's return value was: {}".format(value))
26
27
28app = App()
29Debugger().register(app)

Example Session:

 1$ python -i ../app.py
 2>>> x = app.fire(test())
 3>>> x.notify = True
 4>>> app.tick()
 5<registered[*] (<Debugger/* 27798:MainThread (queued=0) [S]>, <App/* 27798:MainThread (queued=1) [S]> )>
 6<test[*] ( )>
 7>>> app.tick()
 8<hello[*] ( )>
 9>>> app.tick()
10<test_value_changed[<App/* 27798:MainThread (queued=0) [S]>] (<Value ('Hello World!') result=True; errors=False; for <test[*] ( )> )>
11>>> app.tick()
12>>> x
13<Value ('Hello World!') result=True; errors=False; for <test[*] ( )>
14>>> x.value
15'Hello World!'
16>>>

The Value.notify attribute can also be set to the name of an event which should be used to fire the value_changed event to.

If the form x.notify = True used then the event that gets fired is a concatenation of the original event and the value_changed event. e.g: foo_value_changed.

Note

This is a bit advanced and should only be used by experienced users of the circuits framework. If you simply want basic synchronization of event handlers it’s recommended that you try the circuits.Component.call() and circuits.Component.wait() synchronization primitives first.