Changes between Version 4 and Version 5 of Documentation/SystemQueue

Timestamp:

Dec 17, 2008, 1:31:34 PM (16 years ago)

Author:

Christoph Mayer

Comment:

--

Documentation/SystemQueue

@@ -54 +54 @@
 }}}
 
+ 4. Next, define a new event type for you in your {{{.cpp}}} file. This event will be scheduled into the !SystemQueue:
+
+{{{
+#!cpp 
+SystemEventType MyEventType("My new event type!");
+}}}
+
+ 5. In your functionality where you want to synchronized yourself into the main Ariba thread using the !SystemQueue, create the event and insert it. You can attach additional information as a {{{void*}}} to the event that you can extract (here, called {{{myInfo}}}), once in the event handler function:
+
+{{{
+#!cpp  
+SystemQueue::instance().scheduleEvent( 
+    SystemEvent( this, MyEventType, myInfo));                                   
+}}}
+
+ 6. Your event handler will be called asynchronously and in sync with the Ariba main thread. You can also extract the additional information ({{{myInfo}}}) from the event. In this handler function you are the only event that is currently executed. Therefore, you can be sure that no other code in executing in parallel and need not to take any care of threading issues or mutexes.
+
+{{{
+#!cpp   
+void MyClass::handleSystemEvent(const SystemEvent& event){
+    MyInfo* info = event.getData<MyInfo>();
+    ....
+}
+}}}
 
 == Using Blocking Code == 
 
+There may be times, when you wish you could use blocking functionality in your code. This is possible with the help of the {{{BlockingMethod}}} function provided by Ariba. If you would just block, this would stall the complete Ariba architecture. Therefore, if you need to do blocking functionality, two things have to be taken care of:
+ 
+ * Switching into a new thread where blocking does not affect the main Ariba thread.
+ * Synchronizing back into the main Ariba thread to perform notification etc. of other components if needed.
+ 
+Both of these issues are handled by the {{{BlockingMethod}}} class that you can use to easily implement your blocking functionality. To implement blocking functionality, perform the following steps:
 
+ 1. Include the header and using directives for the {{{BlockingMethod}}} in your {{{.h}}} file:
+ 
+{{{
+#!cpp   
+#include spovnet/common/BlockingMethod.h"
+using spovnet::common::BlockingMethod;
+}}}
+
+ 2. Derive a new class from {{{BlockingMethod}}}:
+ 
+{{{
+#!cpp   
+class MyClass : public BlockingMethod {
+}}}
+
+ 3. Declare the pure virtual function from {{{BlockingMethod}}} in your new class:
+ 
+{{{
+#!cpp   
+virtual void dispatchFunction();
+virtual void blockingFunction();
+}}}
+
+ 4. Finally, implement those two functions in your {{{.cpp}}} file
+
+{{{
+#!cpp
+void MyClass::dispatchFunction(){
+   ...
+}
+
+void MyClass::blockingFunction(){
+   ...
+}
+}}}
+
+ 5. Write the code that blocks execution into the {{{blockingFunction}}}. Implement code that you want to execute once synchronized with the main thread after the blocking into the {{{dispatchFunction}}}. In the {{{dispatchFunction}}} you can safely call other modules etc. from Ariba, because this function will be executed by the !SystemQueue once in sync with the main thread! 
+ 
+ 6. From your {{{blockingFunction}}} you can then call {{{MyClass::dispatch}}} to get synchronized back into the main thread once your blocking functionality is done. This will result in {{{MyClass::dispatchFunction}}} being called asynchronously and in sync with the main thread. 
+ 
+The mechanism works by running the blocking functionality automatically in a new thread, therefore not blocking execution of the main Ariba thread. Once you call {{{dispatch}}} an event is generated that results in calling {{{dispatchFunction}}} from the main thread.