# 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.