diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/COMPARISON.md | 89 | ||||
-rw-r--r-- | docs/GETTING_STARTED.md (renamed from docs/untitled.txt) | 0 | ||||
-rw-r--r-- | docs/NATIVE_CODE.md | 142 |
3 files changed, 231 insertions, 0 deletions
diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md new file mode 100644 index 0000000..94e8d3b --- /dev/null +++ b/docs/COMPARISON.md @@ -0,0 +1,89 @@ +# Comparison of SCXML Interpreters + +In this document, I will make an attempt to compare and measure the performance +of the various, freely available SCXML interpreters. If you are the author of +one of these interpreters and feel that I misrepresented your work, please do +not hesitate to contact me and I will reevaluate / correct any factual errors. + +This selection is based on the list of available implementations on the [SCXML +wiki](https://en.wikipedia.org/wiki/SCXML) page, plus a few interpreters I know +from the [W3C mailing list](https://lists.w3.org/Archives/Public/www-voice/) +and the [SCXML workshops](http://scxmlworkshop.de). I will list all +interpreters known to me, but only benchmark those that pass the W3C IRP tests +as is required for an actual SCXML interpreter. + +# Methodology + +The benchmarks were performed with a [huge +SCXML](https://github.com/tklab-tud/uscxml/tree/master/test/w3c/compound) file +containing all of the automatic W3C IRP tests that do not rely on timeouts to +pass. + +## scxmlcc + +| Platforms | Tested on | Tested | Website | +|---------------|---------------------|------------------|---------------| +| Linux only | Debian Jessie 64Bit | **No**: Subset of SCXML implemented is insufficient for SCXML IRP tests. | [http://scxmlcc.org](http://scxmlcc.org) | + +### How to build + + $ sudo apt-get install build-essential libboost-all-dev autorevision + $ git clone https://github.com/jp-embedded/scxmlcc.git + $ cd scxmlcc/src + $ make + +### Evaluation + + $ ./scxmlcc -i ./test-ecma-all.scxml |sort |uniq + warning: event asteriks not currently supported + warning: event tokens not currently supported + warning: parallel support is not fully implemented/tested + warning: unknown action type 'script' + warning: unknown item 'assign' in <onentry> or <onexit> + warning: unknown item 'assign' in <transition> + warning: unknown item 'cancel' in <transition> + warning: unknown item 'datamodel' in <state> + warning: unknown item 'donedata' in <state> + warning: unknown item 'foreach' in <onentry> or <onexit> + warning: unknown item 'if' in <onentry> or <onexit> + warning: unknown item 'invoke' in <state> + warning: unknown item 'send' in <onentry> or <onexit> + warning: unknown item 'send' in <transition> + +The subset of SCXML implemented in <tt>scxmlcc</tt> is insufficient to run the +performance / compliance benchmarks. + +## SCXML Lab + +| Platforms | Tested on | Tested | Website | +|---------------|---------------------|-----------|---------------| +| HTML5 | Safari 9.0.3 | **No**: Subset of SCXML implemented is insufficient for SCXML IRP tests. | [http://www.ling.gu.se/~lager/Labs/SCXML-Lab/](http://www.ling.gu.se/~lager/Labs/SCXML-Lab/) | + +I pasted the file above into their web-frontend and got a <tt>validation-error</tt> + + Unexpected attribute 'datamodel' in <scxml>. Hint: + Valid attributes are: 'id', 'initialstate', 'version', 'xmlns'. + +The <tt>datamodel</tt> is indeed not required for a compliant interpreter, but +we will not be able to pass any meaningful subset of the SCXML IRP tests +without support for a datamodel. + +## Legian + +| Platforms | Tested on | Tested | Website | +|---------------|---------------------|-----------|---------------| +| Java | Java(TM) SE (build 1.8.0_45-b14) | **No**: Subset of SCXML implemented is insufficient for SCXML IRP tests. | [https://github.com/pelatimtt/Legian](https://github.com/pelatimtt/Legian/) | + +Does not claim W3C compliance and will, therefore, not pass the compound IRP tests. + +## Qt SCXML Engine + +| Platforms | Tested on | Tested | Website | +|---------------|---------------------|-----------|---------------| +| Any | Mac OSX 10.11.3 with Macports 2.3.4 | **No**: Subset of SCXML implemented is insufficient for SCXML IRP tests. | [https://qt.gitorious.org/qt-labs/scxml](https://qt.gitorious.org/qt-labs/scxml/) | + +[No +support](https://qt.gitorious.org/qt-labs/scxml?p=qt-labs:scxml.git;a=blob_plain;f=doc/scxml.qdoc;hb=HEAD) +for <tt><donedata></tt>, <tt><finalize></tt>. Furthermore the +<tt>profile</tt> (now <tt>datamodel</tt> with finalized SCXML recommendation) +attribute is ignored. diff --git a/docs/untitled.txt b/docs/GETTING_STARTED.md index 8c585bf..8c585bf 100644 --- a/docs/untitled.txt +++ b/docs/GETTING_STARTED.md diff --git a/docs/NATIVE_CODE.md b/docs/NATIVE_CODE.md new file mode 100644 index 0000000..91af599 --- /dev/null +++ b/docs/NATIVE_CODE.md @@ -0,0 +1,142 @@ +# Generating Native Code + +You can use the <tt>uscxml-transform</tt> tool to create native code from an +SCXML document. In this case, you will not use an instance of the +<tt>uscxml::Interpreter</tt> class, but instantiate an SCXML context from a +native description of the state-chart. + +## Embedding ANSI C + +To embed the control flow described within an SCXML document in most variances +of the C language, we provide a transformation onto ANSI C (C89) as a proper +subset of virtually any more modern C/C++ dialect. There are two general +approaches to achieve this. In any case, you need to transform your SCXML +state-chart onto ANSI C by invoking <tt>uscxml-transform</tt>: + + $ uscxml-transform -tc -i INPUT_FILE -o OUTPUT_FILE + +This transformation will create a single file that you can compile and link or +include directly. I advice to include the file into another compilation unit +and not to compile it directly, as it allows for more convenience and is +generally a more flexible approach. The file will contain: + +1. A set of pre-processor **macros** for convenience and definitions, all starting +with an <tt>USCXML_</tt> prefix. Of special note are the following macros that +allow you to influence important characteristics of you state-machine. + + * <tt>**USCXML_NR_STATES_TYPE** / **USCXML_NR_TRANS_TYPE**</tt>: + + The type for unsigned integers that is of sufficient size to contain + the number of states / transitions of your largest state machine. The + transformation will automatically choose one of the <tt>uint*_t</tt> + types, though a popular extension, they are only available in C99 + (<tt>stdint.h</tt>). Also, if you like to reuse parts of the file (e.g. + the types below) in another compilation unit, you might need to + predefine them explicitly to a sufficient size. + + * <tt>**USCXML_MAX_NR_STATES_BYTES** / **USCXML_MAX_NR_TRANS_BYTES**</tt>: + + The minimial size for the bit-arrays as <tt>char[N]</tt> containing the + states and transitions in the various types and on the stack during a + microstep. It has to be larger or equal to the smallest positive + integer that, when multiplied by 8 is larger or equal to the number of + states and transitions repsectively. + + In other words, make sure that + <tt>states[USCXML_MAX_NR_STATES_BYTES]</tt> has room for one bit per + state and <tt>transitions[USCXML_MAX_NR_TRANS_BYTES]</tt> for one bit + per transition. + + * There are some other macros defined, but they are rather for + micro-optimizations. Have a look at a generated file. + +2. All compound data **types** (<tt>struct</tt>) to encode an SCXML state-machine. +These will refer to the macros above to require memory for a state-chart's +states and transitions, so make sure that the macros are set if you +conditionally include parts of the generated file and double-check that the +type definitions are the same in every compilation unit if you want to access +state-machines from other units (i.e. same value for macros above!). + +3. The actual **symbols** for one or many state-machines from the input SCXML +file. Their identifiers are all prefixed by an identifier derived from the +content of a given SCXML document. As such, if you transform any given SCXML +document twice, you might end up with duplicate symbols, yet again, the +state-chart's will be functionally identical as they contained the same content. + + In order for not having to guess the prefix when referring to any machine + in application code, the tranformation will define three additional macros: + + #ifndef USCXML_MACHINE + # define USCXML_MACHINE _uscxml_BC220711_machine + #endif + #define USCXML_MACHINE_0 _uscxml_BC220711_machine + #define USCXML_MACHINE_NAME_HERE _uscxml_BC220711_machine + + The first macro is useful if you only transformed a single SCXML + state-chart as it will always refer to the very first state-chart + encountered. If there is more than one SCXML state-chart within a document + (i.e. an invocation of nested machines) you can also refer to them by index + or their eventual name. + +4. Some **helper functions**, most notably bit operations for arbitrary length +bit arrays. + +5. The **micro-step function** <tt>uscxml_step</tt>, which will perform a +micro-step on a given context and delegate control flow accordingly. + +These elements are always contained and you can, selectively, disable their +inclusion by pre-defining respective macros (have a look at a generated source +file). + +Now in order to actually use an SCXML document to manage the control flow among +a set of functions, there are two general approaches. Both use the generated +ANSI C source code above, but require more or less resources at runtime as +detailled below. + +### Fully Compliant + +An SCXML interpreter does more than to perform a series of microsteps for event +over a set of states and transitions and there are quite a few responsibilities +not implemented in the generated ANSI C code: + +1. **Event Queues**: + + A compliant interpreter is required to maintain two event queues, an + internal and an external one. With the generated ANSI C source, these are + integrated via four callbacks and will need to be implemented in + user-supplied code: + + 1. <tt>**uscxml_ctx.dequeue_internal**</tt>: This callback is invoked + whenever the interpreter needs an event from the internal event queue. It + is passed an instance of a <tt>uscxml_ctx</tt> structure and is supposed to + return an opaque pointer to an event. If the internal queue is empty, + <tt>NULL</tt> is to be returned. + + 2. <tt>**uscxml_ctx.dequeue_external**</tt>: This callback is functionally + equivalent to <tt>uscxml_ctx.dequeue_internal</tt> but invoked, when an + external event is to be dequeued. + + 3. <tt>**uscxml_ctx.exec_content_send**</tt>: Whenever there is an + <tt><send></tt> element encountered in executable content, the generated + ANSI C code will invoke this callback with a context and an + <tt>uscxml_elem_send</tt> instance and the user code registered at the + callback is expected to handle the send request as per recommendation. + + 4. <tt>**uscxml_ctx.exec_content_raise**</tt>: This callback is invoked for + any <tt><raise></tt> element processed as part of executable content and + is expected to deliver an event to the internal event queue. + +2. **Transition Matching / Enabling** + + An event will match and enable a set of transitions. The generated ANSI C + source will already make sure that only valid sets of transitions can be + selected to constitute the optimal transition set for a microstep, but + user-supplied code will have to decide whether a transition is matched and + enabled. This is done via the <tt>**uscxml_ctx.is_enabled**</tt> callback. + It receives a context, a <tt>uscxml_transition</tt> structure and the + opaque event pointer and will have to return <tt>0</tt> for when the + transition is not matched and enabled by the given event and <tt>1</tt> if + it is. + + +### Light-Weight |