sems/doc/dsm/Readme.dsm.txt

The DonkeySM - state machines as SEMS applications

DonkeySM is a state machine interpreter for SEMS. Application 
or service logic can comfortably and accurately be defined
as state machine, in a simple textual state machine definition 
language, and executed by the dsm module as application in SEMS.

A DSM consists of states and transitions between the states.
One state is the initial state with which the DSM is started. 
The transitions have conditions. If something happens, 
i.e. the session processes an event, the transitions are checked 
in order. If all conditions match, the transition is executed. 
Transitions can contain actions, which are run when the transition 
is executed. States can have actions that are executed on entering 
the state, and on leaving the state. If a transition is executed, 
first the leaving actions of the old state, then the transition 
actions, and finally the entering actions of the new state are 
executed.

DSMs can be defined in a hierarchical manner: Another DSM can be 
called as sub-DSM, or one can jump to another DSM, ignoring where
we came from.

In the DSM language, there is support for 
 - functions (groups of action commands)
 - if condition { action; action; } else { action; action; }
 - for loops: 
     - for ($x in range(0, 5)) { action; action; }
     - for ($x in $myarray) { action; action; }
     - for ($k,v in $mystruct) { action; action; }

A session (call) in the DonkeySM has a set of named (string) variables.
The variables may be used as parameter to most conditions and 
actions, by prepending the variable name with a dollar sign. The
parameters of an event (e.g. the key on key press) may be accessed
by prepending the name with a hash (e.g. #key). There are also 
'selects' with which a set of dialog properties can be accessed 
(e.g. @local_tag).

The DonkeySM can be extended by modules, which add new conditions
and actions to the language. This way, menuing system etc can be 
implemented as DSM, while complex logic or processing can efficitently 
be implemented in C++. Modules can act on new sessions, and have a 
initialization function that is called when the module is loaded.
DonkeySM also has built in actions to call 
DI methods from other modules. 

Actions (and conditions) can throw exceptions. Once an exception occurs,
execution of the current actions is interrupted. Exceptions are handled
this way that special "exception" transitions are executed. Exception
transitions are marked with "exception" in the conditions list. Once the
FSM is in exception handling, only exception transitions are followed.
DSMs may throw exceptions with the throw(<type>) action or the 
throwOnError() action.

DSM can cache a set of prompts, configured at start, in memory 
using PromptCollection.

A patch for fmsc 1.0.4 from the graphical FSM editor fsme 
(http://fsme.sf.net) is available, so DSMs can be defined in 
click-n-drag fashion and compiled to SEMS DSM diagrams.

DSM scripts can include other scripts by using the #include "script.dsm"
directive. That loads a script from the load path (where the current 
script resides), unless an absolute path is given (e.g. 
#include "/path/to/script).

There is SIP Session Timer (RFC4028) support, which is configured in 
dsm.conf. By default, session timers are turned not enabled.

SystemDSMs
==========

A system DSM is executed without a corresponding call. This can be useful 
e.g. to execute something periodically, to make a call generator etc.

Another use of system DSMs is to centralize application logic that spans
several calls. The call legs send updates in theirs states as events to
the central system DSM, which centrally processes those events and sends
commands as events back to the call legs, which then process those commands.

Obviously, only limited functionality is available in System DSMs, all 
call and media related functionality is not available (and will throw 
exceptions with type 'core').

A system DSM receives the "startup" event on start of the server, or if 
it is created via createSystemDSM DI call. It gets a "reload" event if the
system DSM is created by a live config reload.

On server shutdown, a system DSM receives a "system" event with 
"ServerShutdown" as type. 

See test_system_event.dsm example for an example how to handle server
start and reload.

DI commands
===========

DI commands allow interaction with DSM calls, and DSM script reload:

postDSMEvent(string call_id, [ [[param0,val0],[param1,val1],...] ]
 post a DSM event into a call. can be used to interact with running
 calls in DSM. See DSM + monitoring + DI example in 
 examples/dsm_di_monit. 

 Example: 
   s.postDSMEvent(call_id, [['action', 'take'],['roomname', 'realworld']])


reloadDSMs()
  reload all DSMs from config file (load_diags) from main config
  - DSM is loaded with main config

loadDSM(string diag_name)
  load DSM with name diag_name, paths are taken from config file
  - DSM is loaded with main config

loadDSMWithPaths(string diag_name, string diag_path, string mod_path)
  load DSM with specified paths
  - DSM is loaded with main config

preloadModules()
  preload all modules specified in config file (preload_mods)

preloadModule(string mod_name, string mod_path)
  preload module from specific path 

hasDSM(string diag_name, [string config])
  returns 1 if DSM with diag_name is loaded, 0 if not
  if config empty or not given, DSM of main config will be listed

listDSMs([string config])
  return list of loaded DSMs
  if config empty or not given, DSM of main config will be listed

registerApplication(string diag_name, [string config])
  register DSM with name diag_name as application in SEMS
  (e.g. to be used with application=$(apphdr), $(ruri.param) 
  or $(ruri.user)
  if config empty or not given, DSM is assumed to be in main config

loadConfig(string conf_file_name, string conf_name)
  (re)load application bundle ("app bundle"), configuration and scripts
  like a file in conf_dir

createSystemDSM(string conf_name, string start_diag)
  run a system DSM (i.e. a DSM thread not connected to a session)
  using scripts/configuration from conf_name. 
  conf_name=='main' for main scripts/main config (from dsm.conf)

More info
=========
 o doc/dsm_syntax.txt has a quick reference for dsm syntax
 o doc/examples/ and lib/ some example DSMs
 o doc/examples/dsm_di_monit example on interfacing with DSM
 o mods/ (will) have modules

Internals
=========
The DSMStateEngine has a set of DSM diagrams which are loaded by 
the DSMStateDiagramCollection from text file and interpreted by
the DSMChartReader, a simple stack based tokenizing compiler.

DSMCall, which implement the DSMSession interface (additionally
to being an AmSession), run DSMStateEngine::runEvent for every event 
that occurs that should be processed by the engine (e.g. Audio event, 
onBye, ...). 

The DSMStateEngine checks every condition of the active state whether
it matches. If all match, the exit actions of the current state, the 
transition actions and then the enter actions of the next state are 
executed. The DSMCondition::match and DSMAction::execute functions
get the event parameters and the session as parameters, so that they
can operate on variables, implement selects etc. 

The DSMCall implementation is very simple, it uses a playlist and 
has PromptCollection to simply play prompts etc.

DSMCoreModule is a 'built in' module that implements the basic 
conditions (test(), hangup() etc) and actions (set(), playFile(), DI 
etc).

Roadmap
=======

On the roadmap is the possibility for modules to be the session factory
used for creating the new session. As the DSMSession is mostly an abstract 
interface, other session types can easily be implemented, and their 
functionality be exposed to the DSM interpreter by custom actions and 
conditions that interact with that specific session type.

As the call state representation is nicely encapsulated here, this can 
also provide an abstraction layer on which active call replication can 
be implemented (rather than re-doing that for every application).

Q&A
===

Why "Donkey" SM? 
 Thanks Atle for the name: "I dont know why.. but my first thought
 when I read good name for FSM interpreter was Donkey. The reason for the
 name is that you put alot of things ontop of a donkey, and let it carry
 it arround.. and this is the same.. you put loads of stuf ontop.. and it
 carries it."

What is repost()? 
 If an event should be reevaluated, e.g. by the transitions of another 
 state or the initial state of another DSM which is called with callFSM/ 
 jumpFSM, repost() can be called, which signals the interpreter to
 evaluate the current event again.

Is the diagram interpreted or compiled? 
 DonkeySM reads the DSM script and creates an internal representation 
 (DSM classes in STL containers). This way it can be executed very
 efficiently.

map<string, string> var; - Are you crazy? E stands for Express!
 yes, right, there would be more efficient ways to implement
 that.  Anyway, in my experience one mostly has to manipulate and 
 check strings, and it is just very comfortable to do it this way.
 OTOH, if in a normal call there is a transition maybe on average 
 every 10 seconds, for which 5 conditions are checked, it is not 
 so much an impact on performance, considering that we are processing
 an audio packet every 20 ms.

You rely too heavily on polymorphism and RTTI - one dynamic_cast for 
each condition of each transition is way too heavy!
 Sure, but as noted above, there should not be heavy processing done
 in the DSM. If you need this, then consider writing your app entirely 
 in C++.

SEMS has a dynamically typed type (AmArg), why not use that one for 
variables? That would also make DI simpler. 
 a patch is very welcome, best to semsdev list: semsdev@iptel.org or 
 the tracker: http://tracker.iptel.org.
 There is also the avar array ("AmArg-Var"), which can hold AmArg 
 variables.

some performance numbers? 
 unfortunately not yet for running DSMs. DSM processing is actually fast: 
 a (quite simple) 3 state 5 transition DSM compiles in 0.2ms on P-M 2GHz.
 So the diagram could actually be read when the call is setup, or DSMs could
 load other DSMs (e.g. loadFSM() action)