Differences

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

--- developer:sequencer:usage [2015/02/10 17:33] – abajric
+++ developer:sequencer:usage [Unknown date] (current) – removed - external edit (Unknown date) 127.0.0.1
@@ Line 1: / Line 1: @@
-======Sequencer Usage======
-This page describes the usage of the sequencer in the EEROS framework.
-===== Sequencer =====
-Create an instance of the sequencer. If its the first sequencer you define, it will automatically be the main sequencer. Start it with the method //start()//. The main program may terminate when the main sequencer has terminated.
-<code c>
-  Sequencer mainSequencer("MainSequencer");  // define sequencer
-  MySequence sequence("MySequence", mainSequencer); // define sequence
-  mainSequencer.start();
-  while(!mainSequencer.isTerminated()){
-    cout << "waiting for executor to terminate..." << std::endl;
-  }
-</code>
-The method //start()// creates a thread, which runs until the //stop()// methode will be called.
-If it is necessary to keep data which is specific to a certain sequencer you may define your own class //**MySequencer**// as an extension of //**Sequencer**// and define the data therein.
-<code c>
-  class MySequencer : public eeros::sequencer::Sequencer
-</code>
-===== Sequence =====
-A sequence is a series of steps. The order has to be defined by the user. A step corresponds to a single method, such as
-<code c>
-  void init();
-  void homed();
-  void move();
-</code>
-Implement each of the method according to its task. Then, derive //**MySequence**// from  //**Sequence**//:
-<code c>
-  class MySequence : public eeros::sequencer::Sequence
-</code>
-As a next step you have to create an instance of //MySequence//. By doing so you can choose a name an assign this sequence to a sequencer.
-<code c>
-  MySequence sequence("MySequence", mainSequencer); // define sequence
-</code>
-Add the steps to the sequence with the method //fillCallBacks()//. This method is a pure virtual method, meaning that the user has to implement it in the derived class //MySequence//.
-And insert this methods in the list of callbacks in your implementation of the method //fillCallBacks()//.
-<code c>
-void MySequence::fillCallBacks(){
-  addCallBack(static_cast<eeros::sequencer::Sequence::method>(&MySequence::init));
-  addCallBack(static_cast<eeros::sequencer::Sequence::method>(&MySequence::homed));
-  addCallBack(static_cast<eeros::sequencer::Sequence::method>(&MySequence::move));
-}
-</code>
-The constructor of //MySequence// should call //addRunnable()// of the member reference //callerThread//. This adds the Sequencer which handles //MySequence// to the list of runnables. All sequence objects are saved in a list, so you can reuse them. Since the sequences are identified by name, the name has to be unique, else you will get an exception.
-<code c>
-/** constructor MySequence
-* name: Name of the Sequence
-* caller: Sequencer to which this sequences belongs
-*/
-MySequence::MySequence(std::string name, eeros::sequencer::Sequencer& caller)
-		: eeros::sequencer::Sequence(name, caller) {
-  callerThread.addRunnable(this);
-}
-</code>
-Do not forget to stop the sequencer by calling //stop()// of the class //Sequencer//.
-<code c>
-  callerThread.stop();
-</code>
-{{ sequenceruml.png?350 | //Class diagramm with Sequencer and Sequence//}}
-===== Subsequence=====
-A subsequence is a sequence, which is called by a step of another sequence. Such a subsequence can be called in a blocking or non-blocking way. Blocking means, that the step waits (or blocks) until the subsequence has finished. Non-blocking means, that subsequence and main sequence run consurrently.
-====Blocking Call of a Subsequence====
-If you want to save your own data in the sequence, so you need to create a new instance of a sequence. This should be done in the desired step (method) of the superior sequence.
-e.g. in the method //MoveBlocking()//
-<code c>
-MyBlockingSubSequence* subSequence = dynamic_cast<MyBlockingSubSequence*>eeros::sequencer::Sequence::getSequence("BlockingSubSequence"));
-if(!subSequence){
-  //callerThread for Blocking Sub Sequence is the same as is in this running Sequence.
-  subSequence = new MyBlockingSubSequence("BlockingSubSequence", callerThread);
-}
-</code>
-**Note:**
-  *In the above lines only one object of //MyBlockingSubSequence// with the name //BlockingSubSequence// is created.
-  *It is not allowed to call the //callerThread.addRunnable(this)// method, because the superior sequence calls the blocking sub-sequence directly by the //run()// method.
-To start the sub-sequence just call //run()//, which calls all methods in the callback list (filled by //fillCallBacks()//). Be sure, that the sub-sequence is terminated before you restart it. This could happen for example in a exception handling ( [[.:..:sequencer_usage:error_handler | Error Handler]] ).
-<code c>
-//Here we wait for the returning of the subSequence.run() method
-while(subSequence->getState() != eeros::sequencer::kSequenceFinished){
-	subSequence->run();
-}
-</code>
-====Non Blocking Call of a Sub-Sequence====
-Remark: Please use pointer for a non blocking call, because the memory referenced by a pointer to an object exists until you delete it, but an object is removed as soon the scope of the method has been left. In the case, in which the both sequences (sequence an sub-sequence) runs contemporaneously, the sub-sequence should not be deleted at the end of the step (method). That's why you should use pointers!
-A non-blocking sub-sequence has to be created as thread, so you need a sub-sequencer, for starting the new thread.
-e.g.:
-<code c>
-MySequencer* subSequencer = new MySequencer("SubSequencer");
-</code>
-Also here you can reuse an existing sub-sequence if you want.
-<code c>
-MyNonBlockingSubSequence* subSequence = dynamic_cast<MyNonBlockingSubSequence*>(eeros::sequencer::Sequence::getSequence("NonBlockingSubSequence"));
-if(!subSequence){
-  subSequence = new MyNonBlockingSubSequence("NonBlockingSubSequence",subSequencer);
-}
-</code>
-**Note:**
-  *The constructor of the //MyNonBlockingSequence// class has to call //callerThread.addRunnable(this)// to add itself to the sub-sequencer runnable list, else the callback methods are not called by the sub-sequencer.
-  *Do not forget to call //callerThread.stop()// in the last step of the sub-sequence.
-As soon as you have created the sub-sequence, you can start the sub-sequencer, which creates the threads to run all steps.
-<code c>
-  subSequencer->start();
-</code>
-In an other step of the superior sequence you can wait until the non-blocking sequence is terminated by using the method: //ExecutorService::waitForSequenceEnd(…);//.
-<code c>
-//Here we wait for the subsequencer Thread
-eeros::sequencer::Sequencer* seq = eeros::sequencer::Sequencer::getMainSequencer()->findSequencer("SubSequencer");
-if(seq && seq->getStatus() != kStopped){
-  ExecutorService::waitForSequenceEnd(seq);
-}
-</code>