Package groupthink :: Module groupthink_base :: Class CausalHandler

Class CausalHandler

The CausalHandler is analogous to the UnorderedHandler, in that it presents an interface with which to build a wide variety of objects with distributed state. The CausalHandler is different from the Unordered in two ways:

The send() method of an CausalHandler returns an index, which must be stored by the CausalObject in connection with the information that was sent. This index is a universal, fully-ordered, strictly causal identifier for each message.
A CausalObject's receive_message method takes two arguments: the message and its index.

As a convenience, there is also

A get_index() method, which provides a new index on each call, always higher than all previous indexes.

CausalObjects are responsible for including index information in the return value of get_history, and processing index information in add_history.

It is noteworthy that CausalHandler is in fact implemented on _top_ of UnorderedHandler. The imposition of ordering does not require lower-level access to the network. This fact of implementation may change in the future, but CausalObjects will not be able to tell the difference.

Instance Methods

[hide private]

__init__(self, name, tube_box)
To construct a CausalHandler, the program must provide a name and a TubeBox.

source code

comparable (and otherwise opaque)

get_index(self)
get_index returns a new index, higher than all previous indexes.

source code

index_trans(self, index, pack)
index_trans is a standard serialization translator for the index format.

source code

send(self, msg, index=None)
send() broadcasts a message to all other participants.

source code

receive_message(self, msg)

source code

add_history(self, hist)

source code

get_history(self)

source code

CausalHandler

copy(self, name)
A convenience function for returning a new CausalHandler derived from this one, with a new name.

source code

iterable(CausalHandler)

get_copies(self)
Returns: All the copies that have been made of this CausalHandler

source code

str

get_name(self)
Returns: the name that was assigned to this CausalHandler

source code

Class Variables

[hide private]

ZERO_INDEX = (0, 0)
the lowest possible index associated with a message in a CausalObject.

Method Details

[hide private]

init(self, name, tube_box)
(Constructor)

source code

To construct a CausalHandler, the program must provide a name and a TubeBox. The name is used to identify the CausalObject; all CausalObjects with the same name on the same Tube should be considered views into the same abstract distributed object.

Parameters:

tube_box (TubeBox)
name (str)

register(self, obj)

source code

This method registers obj as the CausalObject being managed by this Handler. It is called by obj after obj has initialized itself.

Parameters:

obj (CausalObject)

get_index(self)

source code

get_index returns a new index, higher than all previous indexes. The primary reason to use get_index is if you wish two know the index of an item _before_ calling send()

Returns: comparable (and otherwise opaque): a new index

index_trans(self, index, pack)

source code

index_trans is a standard serialization translator for the index format. Thanks to this translator, a CausalObject can and should treat each index as an opaque, comparable object.

send(self, msg, index=None)

source code

send() broadcasts a message to all other participants. If called with one argument, send() broadcasts that message, along with a new index, and returns the index. If called with two arguments, the second may be an index, which will be used for this message. The index must have been acquired using get_index(). In this case, the index must be acquired immediately prior to calling send(). Otherwise, another message may arrive in the interim, causing a violation of causality.

Returns:: index

copy(self, name)

source code

A convenience function for returning a new CausalHandler derived from this one, with a new name. This is safe as long as copy() is called with a different name every time.

Parameters:

name (str)

Returns: CausalHandler

a new CausalHandler, with a name derived from this one

get_copies(self)

source code

Returns: iterable(CausalHandler): All the copies that have been made of this CausalHandler

get_name(self)

source code

Returns: str: the name that was assigned to this CausalHandler

Class Variable Details

[hide private]

ZERO_INDEX

the lowest possible index associated with a message in a CausalObject. This value may be useful to implementors of CausalObjects.

Value:

(0, 0)

Class CausalHandler

__init__(self, name, tube_box) (Constructor)

register(self, obj)

get_index(self)

index_trans(self, index, pack)

send(self, msg, index=None)

copy(self, name)

get_copies(self)

get_name(self)

ZERO_INDEX

init(self, name, tube_box)
(Constructor)