ginsfsm.gaplic

GAplic

Container of gobjs.

GAplic supplies the main loop in a thread o subprocess context.

GAplic has the next methods:

• GAplic.create_gobj()
• GAplic.destroy_gobj()
• GAplic.find_unique_gobj()
• GAplic.send_event_outside()
• GAplic.subscribe_event_outside()
• GAplic.unsubscribe_event_outside()
• GAplic.add_callback()
• GAplic.start()
• GAplic.stop()
• GAplic.mt_subprocess()

A gaplic can run in a thread or subprocess context, always with the same interface.

Auxiliary functions:

To run a GAplic instance like a thread: setup_gaplic_thread().

To run a GAplic instance like a subprocess: setup_gaplic_process().

To use configuration file .ini with PasteDeploy in composite mode: gaplic_factory().

GAplic class

class ginsfsm.gaplic.GAplic(name=None, roles=None, **ini_settings)

Container of gobj’s running under the same process or thread.

Parameters:

• name – name of the gaplic, default is None.
• ini_settings –

  keyword arguments, with the parameters from a ini configfile. The ini settings will be set to all new created gobj by ginsfsm.gobj.GObj.overwrite_parameters() function.

  Note

  The parameters can be dot named to include the named-gobj‘s destination of the parameters.

GAplic is the main boss. Manage the timer’s, event queues, etc. Supplies register, deregister and search or named-events.

Configurable Parameters:

Name	Type	Default value	Description
ini_settings	dict	{}	The ini settings will be set to all new created gobj by overwrite_parameters() function
all_unique_names	bool	False	All named-gobjs are unique-named gobjs
roles	tuple	()	Roles of gaplic
trace_mach	bool	False	Display simple machine activity
logger	None	None
router_enabled	bool	False	True if a (NOT Pyramid) router is enabled.

Diagram:

Example:

from ginsfsm.gaplic import GAplic

if __name__ == "__main__":
    ga = GAplic(name='Example1', roles='')
    ga.create_gobj('test_aplic', GPrincipal, None)
    try:
        ga.start()
    except KeyboardInterrupt:
        print('Program stopped')

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

Factory function to create gobj’s instances.

Subclass of ginsfsm.gobj.GObj.create_gobj() to do something else, like to let unique-named-gobj instances.

Parameters:

• name – Name of the gobj. If the key __unique_name__ passed in kw is True, then the gobj will be a unique-named-gobj and. the GObj._register_unique_gobj() will be called. If GObj._register_unique_gobj() fails, a :exc:GObjError exception will be raised.
• gclass – gclass is the GObj type used to create the new gobj. It’s must be a derived class of ginsfsm.gobj.GObj.
• parent – parent of the new gobj. If None, the gobj will be a principal gobj.
• 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:

  '__unique_name__': Register the gobj as unique name gobj.

Return type:

new gobj instance.

When a gobj is created by the factory function, it’s added to their parent child list ginsfsm.gobj.GObj.dl_childs, and several attributes are created:

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

If the gclass is subclass of ginsfsm.c_sock.GSock two private attributes are added to the created gobj:

• _socket_map: dictionary of open sockets.
• _impl_poll: poll implementation: can be epoll, select, KQueue.. the best found option.

It’s the base of the asynchronous behavior.

static destroy_gobj(gobj)

Destroy a gobj

find_unique_gobj(gobj_name)

Find a unique-named-gobj.

send_event_outside(gaplic_name, role, gobj_name, event_name, subscriber_gobj, origin_role=None, **kw)

Send an event to an external gaplic.

Parameters:

• gaplic – name of external gaplic.
• role – name of external role.
• gobj_name – name of external gobj.
• event_name – name of the event to send.
• subscriber_gobj – subscriber obj that wants receive the response.
• origin_role – specify role if you have two o more roles.
• kw – keyword arguments.

Possible values for kw arguments:

• __subscribe_response__: Bool Subscribe the response of external executed action. Received with the same event.

subscribe_event_outside(gaplic_name, role, gobj_name, event_name, subscriber_gobj, origin_role=None, **kw)

Subscribe an event of an external gaplic by name.

unsubscribe_event_outside(gaplic_name, role, gobj_name, event_name, subscriber_gobj, **kw)

Subscribe an event of an external gaplic by name.

add_callback(callback, *args, **kwargs)

Call the given callback in the next I/O loop iteration.

start()

Run the infinite i/o event loop.

stop()

Signalize the gaplic instance to stop.

mt_subprocess()

Subclass GAplic class and override this function to do extra work in the infinite loop.

Thead context

Running as thread:

ga = GAplic()
worker = setup_gaplic_thread(ga)
worker.start()

ginsfsm.gaplic.setup_gaplic_thread(gaplic)

Run gaplic as thread. Return the worker. You must call worker.start() to run the thread.

class ginsfsm.gaplic.GAplicThreadWorker(gaplic)

Class derived from threading.Thread to run gaplic in thread environment.

run()

Override the threading.Thread.run() method.

Run the gaplic loop in a separate thread.

join(timeout=10.0)

Wait for worker to stop, until timeout seconds.

Subprocess context

Running as subprocess:

ga = GAplic()
worker = setup_gaplic_process(ga)
worker.start()

ginsfsm.gaplic.setup_gaplic_process(gaplic)

Run gaplic as process. Return the worker. You must call worker.start() to run the subprocess.

class ginsfsm.gaplic.GAplicProcessWorker(gaplic)

Class derived from multiprocessing.Process to run gaplic in subprocess environment.

run()

Override the multiprocessing.Process.run() method.

Run the gaplic loop in a separate process.

join(timeout=10.0)

Wait for worker to stop, until timeout seconds.

Runnig several threads or subprocesses:

from ginsfsm.gaplic import GAplic, setup_gaplic_thread

# run one gaplic as thread
ga_srv = GAplic(name='Server', roles='')
srv_worker = setup_gaplic_thread(ga_srv)
srv_worker.start()

ga_cli = GAplic(name='Client', roles='')

try:
    # run the main gaplic as main process
    ga_cli.start()

except (KeyboardInterrupt, SystemExit):
    # stop the main gaplic
    ga_srv.stop()

    # wait to finish the other gaplic
    srv_worker.join()

    print('Program stopped')

Ini file configuration

You can configure and run your gaplic applications with PasteDeploy.

Available are the gcreate and gserve commands, similar to pcreate and pserve of Pyramid.

ginsfsm.gaplic.gaplic_factory(loader, global_conf, **local_conf)

To use with PasteDeploy in composite.

Items of composite section:

main:name of a section that must return a gaplic instance. It will be the principal gaplic. threads:name of sections that must return gaplic instances. They will run in threads. subprocesses:name of sections that must return gaplic instances. They will run in subprocesses. wsgi:name of sections that must return a app paste factory. Wsgi applications are saved as global apps (set_global_app()).

Example:

[composite:main]
use = call:ginsfsm.gaplic:gaplic_factory
main = wsgi-server
wsgi = wsgi-application

[app:wsgi-server]
use = call:ginsfsm.examples.wsgi.simple_wsgi_server:main
host = 0.0.0.0
port = 8000
application = wsgi-application
GSock.trace_dump = true
GObj.trace_mach = true

[app:wsgi-application]
use=call:ginsfsm.examples.wsgi.simple_wsgi_server:paste_app_factory

The prototype for wsgi (paste app factory) is:

def paste_app_factory(global_conf, **local_conf):
    return wsgi-application

The prototype for main, threads and subprocesses is:

def main(global_conf, **local_config):
    return gaplic-instance