User Tools

Site Tools


v051:userguide

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
v051:userguide [2016/10/27 06:40]
ndj94 [Executing models]
v051:userguide [2017/04/24 18:02] (current)
nagy.andras95 [Compilation to C++]
Line 58: Line 58:
 ==== Modeling Language ==== ==== Modeling Language ====
  
-See the [[v050:​language|Language Guide]] to study the txtUML language both in Java syntax (JtxtUML) and in custom syntax (XtxtUML). In case of JtxtUML, the [[http://​txtuml.inf.elte.hu/​releases/​txtuml-v050/​api/​|JavaDoc]] of the API can also be used.+See the [[v050:​language|Language Guide]] to study the txtUML language both in Java syntax (JtxtUML) and in custom syntax (XtxtUML). In case of JtxtUML, the [[http://​txtuml.inf.elte.hu/​releases/​txtuml-v051/​api/​|JavaDoc]] of the API can also be used.
  
 ==== Generating diagrams === ==== Generating diagrams ===
Line 99: Line 99:
 Model executors can be managed through the ''​ModelExecutor''​ interface in the ''​hu.elte.txtuml.api.model.execution''​ package. This interface has two static ''​create''​ methods to instantiate the default executor. The first is without parameters while the second one takes a single ''​String''​ argument as an optional name for the new executor instance. This name will appear in the automatic logs. Model executors can be managed through the ''​ModelExecutor''​ interface in the ''​hu.elte.txtuml.api.model.execution''​ package. This interface has two static ''​create''​ methods to instantiate the default executor. The first is without parameters while the second one takes a single ''​String''​ argument as an optional name for the new executor instance. This name will appear in the automatic logs.
  
-In the simplest case, a main Java class that executes a model and does nothing else, would look like this:+In the simplest case, a main Java class that solely ​executes a model would look like this:
  
 <code java> <code java>
Line 105: Line 105:
   public static void main(String[] args) {   public static void main(String[] args) {
     ModelExecutor.create().run( () -> {     ModelExecutor.create().run( () -> {
-      MyClass ​= Action.create(MyClass.class);​ +      MyClass ​instance ​= Action.create(MyClass.class);​ 
-      Action.start(a); +      Action.start(instance); 
-      Action.send(new MySignal(), ​a);+      Action.send(new MySignal(), ​instance);
       // ...       // ...
     });     });
Line 114: Line 114:
 </​code>​ </​code>​
  
-The ''​run''​ method takes a ''​Runnable''​ instance, the //​initialization//​ of the model execution which should create, link, start and send signals to the model objects which are required at the beginning the model execution. This initialization code will run as part of the model, so any action that is allowed in the model is also allowed here.+The ''​run''​ method takes a ''​Runnable''​ instance, the //​initialization//​ of the model execution which should create, link, start and send signals to the model objects which are required at the beginning ​of the model execution. This initialization code will run as part of the model, so any action that is allowed in the model is also allowed here.
  
-The model executor writes log messages to the console and to a log file. Runtime errors and warnings are always logged but there is an optional trace logging which reports ​about all important events during the model execution, for example, when a state machine of a model object leaves or enters a state. This trace logging is switched off by default but can be switched on with the ''​setTraceLogging''​ method. It is important to call this method //before// starting the model execution with the run method as it will fail with an exception otherwise.+The model executor writes log messages to the console and to a log file. Runtime errors and warnings are always logged but there is an optional trace logging which reports all important events during the model execution, for example, when a state machine of a model object leaves or enters a state. This trace logging is switched off by default but can be switched on with the ''​setTraceLogging''​ method. It is important to call this method //before// starting the model execution with the run method as it will fail with an [[http://​txtuml.inf.elte.hu/​releases/​txtuml-v051/​api/​hu/​elte/​txtuml/​api/​model/​execution/​LockedModelExecutorException.html|exception]] otherwise.
  
 <code java> <code java>
Line 124: Line 124:
 </​code>​ </​code>​
  
-This knowledge about model executors is more than enough to test your first models but if you wish to use them in a complex Java applicationfor example, if you would like to create a GUI through which users may communicate with your model, you have to keep in mind some fundamentals of txtUML model execution.+This knowledge about model executors is more than enough to test your first models but if you wish to use them in a complex Java application ​(for example, if you would like to create a UI through which users may communicate with your model), you have to keep in mind some fundamentals of txtUML model execution.
  
-The most important thing to know is that models always run on their own thread(s)created and managed by the model executor and not on the thread on which you create the model executor instance. However, ​every required synchronization can easily ​be done with methods of the ''​ModelExecutor''​ interface.+The most important thing to know is that models always run on their own thread(s) ​– created and managed by the model executor ​– and not on the thread on which you create the model executor instance. However, ​most required synchronization can be easily ​done with methods of the ''​ModelExecutor''​ interface.
  
-The fastest and most basic way to start model execution is with the ''​start(Runnable)''​ method, which creates a new model executor thread, starts the execution on it by running ​the initialization code and returns instantly. ​For all available execution optionssee the [[http://​txtuml.inf.elte.hu/​releases/​txtuml-v051/​api/​hu/​elte/​txtuml/​api/​model/​execution/​ModelExecutor.html|JavaDoc]] ​of the ''​ModelExecutor''​ interface.+The fastest and most basic way to start model execution is with the ''​start(Runnable)''​ method, which creates a new model executor thread, starts the execution on it by calling ​the initialization codeand returns instantly. ​This is usefulfor example, if you wish to start the execution ​of the model and later the model connects itself to a UI through external classes (classes that are part of the model but can contain plain Java code in their methods)Keep in mind, however, that any method ​of an external class called by model objects will be run on a model executor thread and if you wish to access other threads from that code, you will need to manually synchronize with the tools of Java.
  
 +If you want to make sure that the model has been initialized (that is, the initialization code has been executed), you can call the ''​awaitInitialization()''​ method of the executor. It is useful, for example, when you need references to model objects to send signals to them from a UI, and you need to be sure that some fields are filled with value.
  
 +<code java>
 +public class Tester {
 + 
 +  private static MyClass instance;
 +
 +  public static void main(String[] args) {
 +    ModelExecutor.create().start( () -> {
 +      instance = Action.create(MyClass.class);​
 +      Action.start(instance);​
 +      // ...
 +    }).awaitInitialization();​
 +    API.send(new MySignal(), instance);
 +    // this call is safe, instance is guaranteed to be non-null here
 +  }
 +}
 +</​code>​
 +
 +Note that outside the initialization code, we used the ''​API.send''​ method instead of ''​Action.send''​. This is important, as only the methods provided by the ''​API''​ class are thread-safe and therefore only these should be used from outside model code. Calling methods and accessing fields of model objects outside model code is also unsafe.
 +
 +A convenience method is provided for the common ''​start(Runnable).awaitInitialization()''​ call, this is ''​launch(Runnable)''​.
 +
 +Another important fundamental of model execution is that it keeps waiting for signals even when it is out of work. This is needed, for example, as one may wish to send signals from a UI long after all previously sent signals have been processed. When it is intended to finish model execution, the method ''​shutdown()''​ should be called. Then the model executor will continue running while it still has any work to do (any signals to process) but when it is out of signals, it will terminate. Calling ''​shutdown()''​ is therefore almost always followed by calling ''​awaitTermination()''​.
 +
 +<code java>
 +public class Tester {
 +  public static void main(String[] args) {
 +    ModelExecutor.create().start( () -> {
 +      MyClass instance = Action.create(MyClass.class);​
 +      Action.start(instance);​
 +      // ...
 +    }).shutdown().awaitTermination();​
 +    System.out.println("​Model execution terminated."​);​
 +  }
 +}
 +</​code>​
 +
 +The ''​start(Runnable).shutdown().awaitTermination()''​ call chain also has a convenience method, that is the previously introduced ''​run(Runnable)''​ method.
  
 +For all available execution options, see the [[http://​txtuml.inf.elte.hu/​releases/​txtuml-v051/​api/​hu/​elte/​txtuml/​api/​model/​execution/​ModelExecutor.html|JavaDoc]] of the ''​ModelExecutor''​ interface.
  
-==== Debugging ​====+=== Debugging ===
  
 Switch to Java or Debug perspective and create a new run/debug configuration. Use ''​Java Application''​ type if you only want to run or debug the model only in text. Use ''​txtUML Application''​ type if state machine animation is required as well. Switch to Java or Debug perspective and create a new run/debug configuration. Use ''​Java Application''​ type if you only want to run or debug the model only in text. Use ''​txtUML Application''​ type if state machine animation is required as well.
Line 178: Line 217:
 If there are classes with no groups aligned to them, a default implicit group will be created which contains these classes. It will be configured with the default values shown above. ​ If there are classes with no groups aligned to them, a default implicit group will be created which contains these classes. It will be configured with the default values shown above. ​
  
-Examples: +Example:
- +
-<​code>​ +
-class DefaultConfiguration extends Configuration {} +
-</​code>​ +
- +
-This means that all of the classes will be grouped in the default group.+
  
 <​code>​ <​code>​
Line 219: Line 252:
 cmake -G "MinGW Makefiles"​ -D CMAKE_BUILD_TYPE=Release .. cmake -G "MinGW Makefiles"​ -D CMAKE_BUILD_TYPE=Release ..
 </​code>​ </​code>​
- 
v051/userguide.1477543211.txt.gz · Last modified: 2016/10/27 06:40 by ndj94