ginsfsm.gobj

Introduction

An GObj is an object that has an inside simple-machine that defines its behavior.

The communication between gobj‘s happens via event‘s:

GObj has the next methods:

• GObj.start_up()
• GObj.create_gobj()
• GObj.destroy_gobj()
• GObj.send_event()
• GObj.post_event()
• GObj.post_event_from_outside()
• GObj.broadcast_event()
• GObj.subscribe_event()
• GObj.delete_subscription()
• GObj.set_owned_event_filter()
• GObj.overwrite_parameters()
• GObj.overwrite_few_parameters()

And this inherited from ginsfsm.smachine.SMachine:

• ginsfsm.smachine.SMachine.set_new_state()
• ginsfsm.smachine.SMachine.get_current_state()
• ginsfsm.smachine.SMachine.get_event_list()
• ginsfsm.smachine.SMachine.get_output_event_list()

GObj has the next public attributes:

• GObj.name
• GObj.parent
• GObj.dl_childs

Events to manage events:

• sending events:

  • sending events by direct delivery: GObj.send_event().
  • sending events by queues: GObj.post_event().
  • sending events from outside world: GObj.post_event_from_outside().
  • sending events to subscribers: GObj.broadcast_event().

• receiving events:

  • directly from another gobj‘s who knows you.
  • subscribing to events by the GObj.subscribe_event() method.
  • you can filtering events being broadcasting with GObj.set_owned_event_filter() method.

Event

class ginsfsm.gobj.Event(destination, event_name, source, **kw)

Collect event properties. This is the argument received by actions.

Parameters:

• destination – destination gobj whom to send the event.
• event_name – event name.
• source – list with path of gobj sources. Firt item source[0] is the original sender gobj. Last item source[-1] is the nearest sender gobj.
• kw – keyword arguments with associated data to event.

GObj

class ginsfsm.gobj.GObj(fsm, gconfig=None)

Well, yes, I’m a very simple brain. Only a machine. But write a good FSM, and I never fail you. Derive me, and write my FSM.

Sample GObj:

class MyGObj(GObj):
    def __init__(self):
        GObj.__init__(self, FSM, GCONFIG)

    def start_up(self):
        ''' Initialization zone.'''

Parameters:

• fsm – FSM simple-machine.
• gconfig – GCONFIG gconfig-template.

name

My name.

Set by create_gobj().

parent

My parent, destination of my events... or not.

Set by create_gobj().

dl_childs

Set of my gobj childs. Me too like be parent!.

set_new_state()

Set a new state. Method to used inside actions, to force the change of state.

Parameters:new_state – new state to set.

new_state must match some of the state names of the machine’s state-list or a StateError exception will be raised.

get_current_state()

Return the name of the current state.

If there is no state it returns None.

get_event_list()

Return the list with the input-event‘s names.

get_output_event_list()

Return the list with the output-event‘s names.

start_up()

Initialization zone.

Well, the __init__ method is used to build the FSM so I need another function to initialize the new gobj. Please, override me, and write here all the code you need to start up the machine: create your owns childs, etc. This function is called by create_gobj() after creating the gobj instance.

create_gobj(name, gclass, parent, **kw)

Factory function to create gobj’s instances.

Parameters:

• name – Name of the gobj.
• gclass – gclass is the GObj type used to create the new gobj. It’s must be a derived class of GObj otherwise a GObjError exception will be raised.
• parent – parent of the new gobj. None if it has no parent. If it’s not None, then must be a derived class of GObj otherwise a GObjError exception will be raised.
• kw –

  Attributes that are added to the new gobj. All the keyword arguments used in the creation function are added as attributes to config object.

  You must consult the attributes supported by each gclass type. The attributes must be defined in the gclass GCONFIG, otherwise they are ignored.

  Special kw:

  '__random_name__': Generate a random gobj name

  TODO: doc re_name

Return type:

new gobj instance.

The factory funcion does:

• Add the gobj to their parent child list GObj.dl_childs,

• If it’s a named-gobj call the GObj.register_unique_gobj().

• Call GObj.start_up().

• Add to the gobj several attributes:

  • name: name of the created gobj.
  • parent: the parent gobj of the created gobj.

static destroy_gobj(gobj)

Destroy a gobj

send_event(destination, event, **kw)

Send event to destination, with associated event data kw.

Parameters:

• destination – Must be a string gobj name or a gobj instance, otherwise a GObjError will be raised. If it’s a string and the gobj name cannot be resolved inside the current gaplic, then the event is post_event() in order to be resolved by the gaplic router.
• event – Must be a string event name or a Event instance, otherwise an EventError will be raised.
• kw – All the keyword arguments are added as attributes to the sent Event instance. You must consult the attributes supported by each machine’s event.

Return type:

return the returned value from the executed action. Return None if the event has been post_event().

If the event-name exists in the machine, but it’s not accepted by the current state, then no exception is raised but the function returns EventNotAcceptedError.

Note

The inject_event() method doesn’t raise EventNotAcceptedError because a machine should run under any circumstances. In any way an action can raise exceptions.

post_event(destination, event, **kw)

Same funcionality as send_event(), but the event is processed by gaplic. If the destination is inside of the current gaplic the event will be sent in the next loop cycle.

broadcast_event(event, **kw)

Broadcast the event to all subscribers.

Parameters:

• event – event to send.
• kw –

  keyword argument with data associated to event.

  Note

  All the keyword arguments are added as attributes to the sent event.

Use this function when you don’t know who are your event’s clients, when you don’t know the gobj destination of your output-event‘s

If there is no subscriptors, the event is not sent.

When an event has several subscriptors, there is a mechanism called event-filter that allows to a subcriptor to own the event and no further spread by more subscribers.

The filter function set by set_owned_event_filter() method, is call with the returned value of an action as argument: If the filter function return True, the event is owned, and the ginsfsm.gobj.GObj.broadcast_event() function doesn’t continue sending the event to other subscribers.

Note

If ginsfsm.gobj.GObj.broadcast_event() function uses ginsfsm.gobj.GObj.post_event(), the event-filter cannot be applied.

static post_event_from_outside(gaplic_name, gobj_name, event, **kw)

Same funcionality as post_event(), but the event is sent from non-gobj world.

subscribe_event(event_name, subscriber_gobj, **kw)

Subscribe to an event.

Parameters:

• event_name – string event name or tuple/list of string event names. If event_name is None then it subscribes to all events. If it’s not None then it must be a valid event name from the output-event list, otherwise a EventError will be raised.
• subscriber_gobj –

  subscriber obj that wants receive the event.

  subscriber_gobj must be:

  • None: the subscriber is the parent.
  • string: the subscriber is a unique-named-gobj.
  • type GObj instance.
  • Deferred callback.

  otherwise otherwise a GObjError will be raised.

• kw – keyword arguments.

Returns:

the subscription object.

Possible values for kw arguments:

• __use_post_event__: bool

  You must set it to True in order to broadcast the events using post-event instead of send-event.

• __rename_event_name__: ‘new event name’

  You can rename the output original event name. The original_event_name attribute is added to the sent event with the value of the original event name.

• __hard_subscription__: bool

  True for permanent subscription.

  This subscription cannot be remove, neither with delete_all_subscriptions(). (Well, with force you can)

• __subscription_reference__: str

  If exists, it will be added as kw in the event broadcast. Can be used by the subscriptor for general purposes.

• __deferred_witout_oevent__: Bool

  If True, the callback is called without event keyword parameter.

• __first_shot__: Bool

  If True then generate a broadcast event to the new subscriber. It’s necesary to have __new_subscriptor_event__ flag, and it’s responsability of the gobj to do the first shot.

delete_subscription(event_name, subscriber_gobj)

Remove subscription.

Parameters:

• event_name – string event name or tuple/list of string event names.
• subscriber_gobj – subscriber gobj.

set_owned_event_filter(filter)

Set a filter function to be used by broadcast_event() function to check the owner of events.

overwrite_parameters(level, **settings)

The parameters in settings must be defined in the gobj.

Parameters:

• level –

  level trace of childs. indicates the depth of the childs as far to change.

  • 0 only this gobj.
  • -1 all tree of childs.
• settings – parameters and their values.

The settings are filtered by the named-gobj or gclass name of this gobj. The parameter name in settings, must be a dot-named, with the first item being the named-gobj o gclass name.

overwrite_few_parameters(parameter_list, **settings)

The parameters in settings must be defined in the gobj.

Parameters:

• parameter_list – write only the parameters in parameter_list.
• settings – parameters and their values.

The settings are filtered by the named-gobj or gclass name of this gobj. The parameter name in settings, must be a dot-named, with the first item being the named-gobj o gclass name.

Exceptions

exception ginsfsm.gobj.GObjError

General GObj exception

exception ginsfsm.gobj.EventError

Raised when the event name doesn’t match any name of the event-list list.

exception ginsfsm.gobj.StateError

Raised when the state name doesn’t match any name of the state-list list.

exception ginsfsm.gobj.MachineError

Raised when something is wrong in the simple-machine definition.

exception ginsfsm.gobj.EventNotAcceptedError

Raised when the event name is good, but the event is not accepted in the current machine’s state.