Documentation/Maemo 5 Developer Guide/DBus/Asynchronous Glib/D-Bus - Revision history

amigadave: /* Asynchronous Method Calls Using GLib Wrappers */ add


amigadave — Mon, 06 Sep 2010 11:31:54 GMT
Asynchronous Method Calls Using GLib Wrappers:  add <code>

		
		
		
		
		
		
		← Older revision
		Revision as of 11:31, 6 September 2010
		
		Line 320:
Line 320:
 == Asynchronous Method Calls Using GLib Wrappers ==  == Asynchronous Method Calls Using GLib Wrappers ==
  
- Sometimes the interface XML is missing, so the dbus-bindings-tool cannot be run to generate the stub code. The GLib wrappers are generic enough to enable building own method calls, when necessary. + Sometimes the interface XML is missing, so the <code>dbus-bindings-tool</code> cannot be run to generate the stub code. The GLib wrappers are generic enough to enable building own method calls, when necessary.
  
 Starting with some known generated stub code to see which parts can possibly be reused with some modifications is usually the easiest solution. This is shown in the last step of this example, in order to make a version of the asynchronous client that works without the stub generator.  Starting with some known generated stub code to see which parts can possibly be reused with some modifications is usually the easiest solution. This is shown in the last step of this example, in order to make a version of the asynchronous client that works without the stub generator.



amigadave: fix vcs links
amigadave — Mon, 06 Sep 2010 10:29:50 GMT
fix vcs links

		
		
		
		
		
		
		← Older revision
		Revision as of 10:29, 6 September 2010
		
		Line 1:
Line 1:
- The example code used below can be found in the [https://garage.maemo.org/svn/maemoexamples/trunk/glib-dbus-signals/ garage svn]. + The example code used below can be found in the [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/ garage svn].
  
 == Asynchronicity in D-Bus clients ==  == Asynchronicity in D-Bus clients ==
Line 13:
Line 13:
 == Slow Test Server ==  == Slow Test Server ==
  
- The only change on the server side is the addition of delays into each of the RPC methods (<code>setvalue1</code>, <code>setvalue2</code>, <code>getvalue1</code> and <code>getvalue2</code>). This delay is added to the start of each function as follows: glib-dbus-async/server.c + The only change on the server side is the addition of delays into each of the RPC methods (<code>setvalue1</code>, <code>setvalue2</code>, <code>getvalue1</code> and <code>getvalue2</code>). This delay is added to the start of each function as follows: [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/server.c glib-dbus-async/server.c]
  
 <source lang="c">  <source lang="c">
Line 95:
Line 95:
 == Asynchronous Method Calls Using Stubs ==  == Asynchronous Method Calls Using Stubs ==
  
- When the <code>glib-bindings-tool</code> is run, it already generates the necessary wrapping stubs to support launching asynchronous method calls. What is then left to do is implementing the callback functions correctly, processing the return errors and launching the method call. glib-dbus-async/client-stubs.c + When the <code>glib-bindings-tool</code> is run, it already generates the necessary wrapping stubs to support launching asynchronous method calls. What is then left to do is implementing the callback functions correctly, processing the return errors and launching the method call. [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/client-stubs.c glib-dbus-async/client-stubs.c]
  
 <source lang="c">  <source lang="c">
Line 103:
Line 103:
 </source>  </source>
  
- The client has been simplified, so that it now only operates on <code>value1</code>. The callback that is called from the stub code is presented next: glib-dbus-async/client-stubs.c + The client has been simplified, so that it now only operates on <code>value1</code>. The callback that is called from the stub code is presented next: [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/client-stubs.c glib-dbus-async/client-stubs.c]
  
 <source lang="c">  <source lang="c">
Line 137:
Line 137:
 Because the method call does not return any data, the parameters for the callback are at minimum (those three are always received). Handling errors must be performed within the callback, because errors could be delayed from the server, and not visible immediately at launch time.  Because the method call does not return any data, the parameters for the callback are at minimum (those three are always received). Handling errors must be performed within the callback, because errors could be delayed from the server, and not visible immediately at launch time.
  
- Note that the callback does not terminate the program on errors. This is done on purpose in order to demonstrate some common asynchronous problems below. The timestamp function is a small utility function to return a pointer to a string, representing the number of seconds because the program started (useful to visualize the order of the different asynchronous events below). glib-dbus-async/client-stubs.c + Note that the callback does not terminate the program on errors. This is done on purpose in order to demonstrate some common asynchronous problems below. The timestamp function is a small utility function to return a pointer to a string, representing the number of seconds because the program started (useful to visualize the order of the different asynchronous events below). [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/client-stubs.c glib-dbus-async/client-stubs.c]
  
 <source lang="c">  <source lang="c">
Line 178:
Line 178:
 </source>  </source>
  
- Using the stub code is rather simple. For each generated synchronous version of a method wrapper, there is also the a _async version of the call. The main difference with the parameters is the removal of the <code>GError</code> pointer (because errors are handled in the callback), and the addition of the callback function to use when the method completes, times out or encounters an error. + Using the stub code is rather simple. For each generated synchronous version of a method wrapper, there is also the a <code>_async</code> version of the call. The main difference with the parameters is the removal of the <code>GError</code> pointer (because errors are handled in the callback), and the addition of the callback function to use when the method completes, times out or encounters an error.
  
 The main function remains the same from the previous client examples (a once-per-second timer is created and run from the mainloop until the program is terminated).  The main function remains the same from the previous client examples (a once-per-second timer is created and run from the mainloop until the program is terminated).
Line 324:
Line 324:
 Starting with some known generated stub code to see which parts can possibly be reused with some modifications is usually the easiest solution. This is shown in the last step of this example, in order to make a version of the asynchronous client that works without the stub generator.  Starting with some known generated stub code to see which parts can possibly be reused with some modifications is usually the easiest solution. This is shown in the last step of this example, in order to make a version of the asynchronous client that works without the stub generator.
  
- The first step is to take a peek at the stub-generated code for the <code>setvalue1</code> call (when used asynchronously): glib-dbus-async/value-client-stub.h + The first step is to take a peek at the stub-generated code for the <code>setvalue1</code> call (when used asynchronously): [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/value-client-stub.h glib-dbus-async/value-client-stub.h]
  
 <source lang="c">  <source lang="c">
Line 362:
Line 362:
 </source>  </source>
  
- What is notable in the code snippet above is that the _async method creates a temporary small structure that holds the pointer to the callback function and a copy of the userdata pointer. This small structure is then passed to <code>dbus_g_proxy_begin_call</code>, along with the address of the generated callback wrapper function (<code>org_maemo_Value_setvalue1_async_callback</code>). The GLib async launcher also takes a function pointer to a function to be used when the supplied "user-data" (in this case, the small structure) needs to be disposed of after the call. Because it uses <code>g_new</code> to allocate the small structure, it passes <code>g_free</code> as the freeing function. Next comes the argument specification for the method call, which obeys the same rules as the LibOSSO ones. + What is notable in the code snippet above is that the <code>_async</code> method creates a temporary small structure that holds the pointer to the callback function and a copy of the userdata pointer. This small structure is then passed to <code>dbus_g_proxy_begin_call</code>, along with the address of the generated callback wrapper function (<code>org_maemo_Value_setvalue1_async_callback</code>). The GLib async launcher also takes a function pointer to a function to be used when the supplied "user-data" (in this case, the small structure) needs to be disposed of after the call. Because it uses <code>g_new</code> to allocate the small structure, it passes <code>g_free</code> as the freeing function. Next comes the argument specification for the method call, which obeys the same rules as the LibOSSO ones.
  
 On RPC completion, the generated callback is invoked and it gets the real callback function pointer and the userdata as its "user-data" parameter. Firs it collects the exit code for the call with <code>dbus_g_proxy_end_call</code>, unpacks the data and invokes the real callback. After returning, the GLib wrappers (which called the generated callback) calls g_free to release the small structure, and the whole RPC launch ends.  On RPC completion, the generated callback is invoked and it gets the real callback function pointer and the userdata as its "user-data" parameter. Firs it collects the exit code for the call with <code>dbus_g_proxy_end_call</code>, unpacks the data and invokes the real callback. After returning, the GLib wrappers (which called the generated callback) calls g_free to release the small structure, and the whole RPC launch ends.
Line 368:
Line 368:
 The next step is to re-implement pretty much the same logic, but also dispose of the small structure because the callback is implemented directly, not as a wrapper-callback (it also omits the need for one memory allocation and one free).  The next step is to re-implement pretty much the same logic, but also dispose of the small structure because the callback is implemented directly, not as a wrapper-callback (it also omits the need for one memory allocation and one free).
  
- The first step for that is to implement the RPC asynchronous launch code: glib-dbus-async/client-glib.c + The first step for that is to implement the RPC asynchronous launch code: [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/client-glib.c glib-dbus-async/client-glib.c]
  
 <source lang="c">  <source lang="c">
Line 413:
Line 413:
 </source>  </source>
  
- And the callback that is invoked on method call completion timeouts or errors: glib-dbus-async/client-glib.c + And the callback that is invoked on method call completion timeouts or errors: [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/client-glib.c glib-dbus-async/client-glib.c]
  
 <source lang="c">  <source lang="c">
Line 457:
Line 457:
 </source>  </source>
  
- The generated stub code is no longer needed, so the dependency rules for the stubless GLib version are different: glib-dbus-async/Makefile + The generated stub code is no longer needed, so the dependency rules for the stubless GLib version are different: [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/Makefile glib-dbus-async/Makefile]
  
 <source lang="make">  <source lang="make">




amigadave: /* Asynchronicity in D-Bus clients */ add link
amigadave — Mon, 06 Sep 2010 10:12:44 GMT
Asynchronicity in D-Bus clients:  add link

		
		
		
		
		
		
		← Older revision
		Revision as of 10:12, 6 September 2010
		
		Line 1:
Line 1:
 The example code used below can be found in the [https://garage.maemo.org/svn/maemoexamples/trunk/glib-dbus-signals/ garage svn].  The example code used below can be found in the [https://garage.maemo.org/svn/maemoexamples/trunk/glib-dbus-signals/ garage svn].
  
- ==  Asynchronicity in D-Bus clients == + == Asynchronicity in D-Bus clients ==
  
 So far all the RPC method calls that have been implemented here have been "fast", meaning that their execution has not depended on an access to slow services or external resources. In real life, however, it is quite likely that some services cannot be provided immediately, but have to wait for some external service to complete, before completing the method call.  So far all the RPC method calls that have been implemented here have been "fast", meaning that their execution has not depended on an access to slow services or external resources. In real life, however, it is quite likely that some services cannot be provided immediately, but have to wait for some external service to complete, before completing the method call.
  
- The GLib wrappers provide a version of making method calls, where the call is launched (almost) immediately, and a callback is executed when the method call returns (either with a return value or an error). + The [[Documentation/Maemo 5 Developer Guide/DBus/Using GLib Wrappers For D-Bus|GLib wrappers]] provide a version of making method calls, where the call is launched (almost) immediately, and a callback is executed when the method call returns (either with a return value or an error).
  
 Using the asynchronous wrappers is important when the program needs to update some kind of status or be reactive to the user (via a GUI or other interface). Otherwise, the program would block waiting for the RPC method to return, and would not be able to refresh the GUI or screen when required. An alternative solution is to use separate threads that run the synchronous methods. However, if this solution is used, synchronization between threads can become an issue, and debugging threaded programs is much harder than debugging single-threaded ones. Furthermore, the implementation of threads might be suboptimal in some environments. For these reasons, the thread scenario is not covered in this guide.  Using the asynchronous wrappers is important when the program needs to update some kind of status or be reactive to the user (via a GUI or other interface). Otherwise, the program would block waiting for the RPC method to return, and would not be able to refresh the GUI or screen when required. An alternative solution is to use separate threads that run the synchronous methods. However, if this solution is used, synchronization between threads can become an issue, and debugging threaded programs is much harder than debugging single-threaded ones. Furthermore, the implementation of threads might be suboptimal in some environments. For these reasons, the thread scenario is not covered in this guide.




amigadave: use 

amigadave — Tue, 17 Aug 2010 09:00:59 GMT
use <code>

		
		
		
		
		
		
		← Older revision
		Revision as of 09:00, 17 August 2010
		
		Line 178:
Line 178:
 </source>  </source>
  
- Using the stub code is rather simple. For each generated synchronous version of a method wrapper, there is also the a _async version of the call. The main difference with the parameters is the removal of the GError pointer (because errors are handled in the callback), and the addition of the callback function to use when the method completes, times out or encounters an error. + Using the stub code is rather simple. For each generated synchronous version of a method wrapper, there is also the a _async version of the call. The main difference with the parameters is the removal of the <code>GError</code> pointer (because errors are handled in the callback), and the addition of the callback function to use when the method completes, times out or encounters an error.
  
 The main function remains the same from the previous client examples (a once-per-second timer is created and run from the mainloop until the program is terminated).  The main function remains the same from the previous client examples (a once-per-second timer is created and run from the mainloop until the program is terminated).
  
- ==  Problems with Asynchronicity == + == Problems with Asynchronicity ==
  
 When the simple test program is built and run, it can be seen that everything starts off quite well. But at some point, problems start to appear:  When the simple test program is built and run, it can be seen that everything starts off quite well. But at some point, problems start to appear:
Line 362:
Line 362:
 </source>  </source>
  
- What is notable in the code snippet above is that the _async method creates a temporary small structure that holds the pointer to the callback function and a copy of the userdata pointer. This small structure is then passed to dbus_g_proxy_begin_call, along with the address of the generated callback wrapper function (org_maemo_Value_setvalue1_async_callback). The GLib async launcher also takes a function pointer to a function to be used when the supplied "user-data" (in this case, the small structure) needs to be disposed of after the call. Because it uses g_new to allocate the small structure, it passes g_free as the freeing function. Next comes the argument specification for the method call, which obeys the same rules as the LibOSSO ones. + What is notable in the code snippet above is that the _async method creates a temporary small structure that holds the pointer to the callback function and a copy of the userdata pointer. This small structure is then passed to <code>dbus_g_proxy_begin_call</code>, along with the address of the generated callback wrapper function (<code>org_maemo_Value_setvalue1_async_callback</code>). The GLib async launcher also takes a function pointer to a function to be used when the supplied "user-data" (in this case, the small structure) needs to be disposed of after the call. Because it uses <code>g_new</code> to allocate the small structure, it passes <code>g_free</code> as the freeing function. Next comes the argument specification for the method call, which obeys the same rules as the LibOSSO ones.
  
- On RPC completion, the generated callback is invoked and it gets the real callback function pointer and the userdata as its "user-data" parameter. Firs it collects the exit code for the call with dbus_g_proxy_end_call, unpacks the data and invokes the real callback. After returning, the GLib wrappers (which called the generated callback) calls g_free to release the small structure, and the whole RPC launch ends. + On RPC completion, the generated callback is invoked and it gets the real callback function pointer and the userdata as its "user-data" parameter. Firs it collects the exit code for the call with <code>dbus_g_proxy_end_call</code>, unpacks the data and invokes the real callback. After returning, the GLib wrappers (which called the generated callback) calls g_free to release the small structure, and the whole RPC launch ends.
  
 The next step is to re-implement pretty much the same logic, but also dispose of the small structure because the callback is implemented directly, not as a wrapper-callback (it also omits the need for one memory allocation and one free).  The next step is to re-implement pretty much the same logic, but also dispose of the small structure because the callback is implemented directly, not as a wrapper-callback (it also omits the need for one memory allocation and one free).




amigadave: wikify slightly, use 
amigadave — Thu, 22 Jul 2010 10:27:15 GMT
wikify slightly, use <source>
Show changes


amigadave: categorise
amigadave — Fri, 12 Feb 2010 12:06:48 GMT
categorise

		
		
		
		
		
		
		← Older revision
		Revision as of 12:06, 12 February 2010
		
		Line 457:
Line 457:
  
 Since the example program logic has not changed from the previous version, testing client-glib is not presented here (it can of course be tested if so desired, because the source code contains the fully working program). This version of the client also launches the method calls without waiting for previous method calls to complete.  Since the example program logic has not changed from the previous version, testing client-glib is not presented here (it can of course be tested if so desired, because the source code contains the fully working program). This version of the client also launches the method calls without waiting for previous method calls to complete.
  + 
  + [[Category:Development]]
  + [[Category:Documentation]]
  + [[Category:Fremantle]]




liox_lang_valid: /* Asynchronous Method Calls Using GLib Wrappers */
liox_lang_valid — Wed, 16 Sep 2009 08:53:49 GMT
Asynchronous Method Calls Using GLib Wrappers

		
		
		
		
		
		
		← Older revision
		Revision as of 08:53, 16 September 2009
		
		Line 316:
Line 316:
 ==  Asynchronous Method Calls Using GLib Wrappers ==  ==  Asynchronous Method Calls Using GLib Wrappers ==
  
- Sometimes the interface XML will be missing, so the dbus-bindings-tool cannot be run to generate the stub code. The GLib wrappers are generic enough to enable building own method calls, when necessary. + Sometimes the interface XML is missing, so the dbus-bindings-tool cannot be run to generate the stub code. The GLib wrappers are generic enough to enable building own method calls, when necessary.
  
- It is often easiest to start with some known generated stub code to see, which parts can possibly be reused with some modifications. This is what is shown in the last step of this example, in order to make a version of the asynchronous client that will work without the stub generator. + Starting with some known generated stub code to see which parts can possibly be reused with some modifications is usually the easiest solution. This is shown in the last step of this example, in order to make a version of the asynchronous client that works without the stub generator.
  
 The first step is to take a peek at the stub-generated code for the setvalue1 call (when used asynchronously): glib-dbus-async/value-client-stub.h  The first step is to take a peek at the stub-generated code for the setvalue1 call (when used asynchronously): glib-dbus-async/value-client-stub.h
Line 356:
Line 356:
   <span><font color="#FF0000">}</font></span></tt>    <span><font color="#FF0000">}</font></span></tt>
  
- What is notable in the code snippet above is that the _async method will create a temporary small structure that will hold the pointer to the callback function, and a copy of the userdata pointer. This small structure will then be passed to dbus_g_proxy_begin_call, along with the address of the generated callback wrapper function (org_maemo_Value_setvalue1_async_callback). The GLib async launcher will also take a function pointer to a function to use when the supplied "user-data" (in this case, the small structure) will need to be disposed of after the call. Since it uses g_new to allocate the small structure, it passes g_free as the freeing function. Next comes the argument specification for the method call, which obeys the same rules as the LibOSSO ones before. + What is notable in the code snippet above is that the _async method creates a temporary small structure that holds the pointer to the callback function and a copy of the userdata pointer. This small structure is then passed to dbus_g_proxy_begin_call, along with the address of the generated callback wrapper function (org_maemo_Value_setvalue1_async_callback). The GLib async launcher also takes a function pointer to a function to be used when the supplied "user-data" (in this case, the small structure) needs to be disposed of after the call. Because it uses g_new to allocate the small structure, it passes g_free as the freeing function. Next comes the argument specification for the method call, which obeys the same rules as the LibOSSO ones.
  
- On RPC completion, the generated callback will be invoked, and it will get the real callback function pointer and the userdata as its "user-data" parameter. It will first collect the exit code for the call with dbus_g_proxy_end_call, unpack the data and invoke the real callback. After returning, the GLib wrappers (which called the generated callback) will call g_free to release the small structure, and the whole RPC launch will end. + On RPC completion, the generated callback is invoked and it gets the real callback function pointer and the userdata as its "user-data" parameter. Firs it collects the exit code for the call with dbus_g_proxy_end_call, unpacks the data and invokes the real callback. After returning, the GLib wrappers (which called the generated callback) calls g_free to release the small structure, and the whole RPC launch ends.
  
- The next step is to re-implement pretty much the same logic, but also dispose of the small structure, since the callback will be implemented directly, not as a wrapper-callback (it also omits the need for one memory allocation and one free). + The next step is to re-implement pretty much the same logic, but also dispose of the small structure because the callback is implemented directly, not as a wrapper-callback (it also omits the need for one memory allocation and one free).
  
 The first step for that is to implement the RPC asynchronous launch code: glib-dbus-async/client-glib.c  The first step for that is to implement the RPC asynchronous launch code: glib-dbus-async/client-glib.c
Line 405:
Line 405:
   <span><font color="#FF0000">}</font></span></tt>    <span><font color="#FF0000">}</font></span></tt>
  
- And the callback that will be invoked on method call completion, timeouts or errors: glib-dbus-async/client-glib.c + And the callback that is invoked on method call completion timeouts or errors: glib-dbus-async/client-glib.c
  
   <tt><span>''<span><font color="#9A1900">/**</font></span>''</span>    <tt><span>''<span><font color="#9A1900">/**</font></span>''</span>
-   <span>''<span><font color="#9A1900"> * This function will be called when the async setvalue1 will either</font></span>''</span> +   <span>''<span><font color="#9A1900"> * This function is called when the async setvalue1 either</font></span>''</span>
-   <span>''<span><font color="#9A1900"> * complete, timeout or fail (same as before). The main difference in</font></span>''</span> +   <span>''<span><font color="#9A1900"> * completes, timeouts or fails (same as before). The main difference in</font></span>''</span>
   <span>''<span><font color="#9A1900"> * using GLib/D-Bus wrappers is that we need to "collect" the return</font></span>''</span>    <span>''<span><font color="#9A1900"> * using GLib/D-Bus wrappers is that we need to "collect" the return</font></span>''</span>
   <span>''<span><font color="#9A1900"> * value (or error). This is done with the _end_call function.</font></span>''</span>    <span>''<span><font color="#9A1900"> * value (or error). This is done with the _end_call function.</font></span>''</span>
Line 447:
Line 447:
   <span><font color="#FF0000">}</font></span></tt>    <span><font color="#FF0000">}</font></span></tt>
  
- The generated stub code is no longer needed, so the dependency rules for the stubless GLib version will also be somewhat different: glib-dbus-async/Makefile + The generated stub code is no longer needed, so the dependency rules for the stubless GLib version are different: glib-dbus-async/Makefile
  
   <tt>client-glib<span><font color="#990000"><nowiki>:</nowiki></font></span> client-glib<span><font color="#990000">.</font></span>o    <tt>client-glib<span><font color="#990000"><nowiki>:</nowiki></font></span> client-glib<span><font color="#990000">.</font></span>o
Line 456:
Line 456:
   </tt>    </tt>
  
- Since the example program logic has not changed from the previous version, testing client-glib is not presented here (it can of course be tested if so desired, since the source code contains the fully working program). This version of the client will also launch the method calls without waiting for previous method calls to complete. + Since the example program logic has not changed from the previous version, testing client-glib is not presented here (it can of course be tested if so desired, because the source code contains the fully working program). This version of the client also launches the method calls without waiting for previous method calls to complete.




liox_lang_valid: /* Problems with Asynchronicity */
liox_lang_valid — Wed, 16 Sep 2009 08:47:31 GMT
Problems with Asynchronicity

		
		
		
		
		
		
		← Older revision
		Revision as of 08:47, 16 September 2009
		
		Line 182:
Line 182:
 ==  Problems with Asynchronicity ==  ==  Problems with Asynchronicity ==
  
- When the simple test program is built and run, it can be seen that everything starts off quite well. But at some point, problems will start to appear: + When the simple test program is built and run, it can be seen that everything starts off quite well. But at some point, problems start to appear:
  
   <code>[sbox-FREMANTLE_X86: /glib-dbus-async] &gt; make client-stubs    <code>[sbox-FREMANTLE_X86: /glib-dbus-async] &gt; make client-stubs
Line 302:
Line 302:
   ...</code>    ...</code>
  
- What happens above is rather subtle. The timer callback in the client launches once per second and performs the RPC method launch. The server, however, still has the 5 second delay for each method call in it. It can be seen that the successive launches go on without any responses for a while. The first response comes back at about 6 seconds from the starting of the client. At this point, the server already has four other outstanding method calls that it has not handled. Slowly the method calls are accumulating at the server end, and it does not deal with them quickly enough to satisfy the client. + What happens above is rather subtle. The timer callback in the client launches once per second and performs the RPC method launch. The server, however, still has the 5 second delay for each method call in it. The successive launches go on without any responses for a while. The first response comes back at about 6 seconds from the starting of the client. At this point, the server already has four other outstanding method calls that it has not handled. Slowly the method calls are accumulating at the server end and it does not deal with them quickly enough to satisfy the client.
  
- After about 30 seconds, it can be seen how the setValue1Completed callback is invoked, but the method call fails. This has managed to trigger the method call timeout mechanism. After this point, all the method calls that have accumulated into the server (into a message queue) will fail in the client, since they all will now return late, even if the server actually does handle them. + After about 30 seconds, the setValue1Completed callback is invoked, but the method call fails. This has managed to trigger the method call timeout mechanism. After this point, all the method calls that have accumulated into the server (into a message queue) fail in the client, since they all return late now, even if the server actually does handle them.
  
- Once the client is terminated, it can be seen that the server is still happily continuing serving the requests, oblivious to the fact that there is no client to process the responses. + Once the client is terminated, the server is still happily continuing serving the requests, oblivious to the fact that there is no client to process the responses.
  
- The above test demonstrates quite brutally that the services need to be designed properly, so that there is a clearly defined protocol what to do in case a method call is delayed. It is also advisable to design a notification protocol to tell clients that something has completed, instead of forcing them to time out. Using D-Bus signals is one way, but it is necessary to take care not to generate signals, when tere is nothing listening to them. This can be done by only sending signals when an long operation finishes (assuming this has been documented as part of the service description). + The above test demonstrates quite brutally that the services need to be designed properly, so that there is a clearly defined protocol what to do in case a method call is delayed. It is also advisable to design a notification protocol to tell clients that something has completed, instead of forcing them to time out. Using D-Bus signals is one way. However, signals must not be generated when nothing is listening to them. This can be done by only sending signals when a long operation finishes (assuming this has been documented as part of the service description).
  
- One partial fix would be for the client to track and make sure that only one method call to one service is outstanding at any given time. So, instead of just blindly launching the RPC methods, it should defer from launching, if it has not yet received a response from the server (and the call has not timed out). + One partial fix is for the client to track and make sure that only one method call to one service is outstanding at any given time. So, instead of just blindly launching the RPC methods, the client should defer from launching RPC methods if it has not yet received a response from the server (and the call has not timed out).
  
- However, this fix is not complete, since the same problem will manifest itself once there are multiple clients running in parallel and requesting the same methods. The proper fix is to make the server capable of serving multiple requests in parallel. Some hints on how to do this are presented later on. + However, this fix is not complete, because the same problem manifests itself once there are multiple clients running in parallel and requesting the same methods. The proper fix is to make the server capable of serving multiple requests in parallel.
  
 ==  Asynchronous Method Calls Using GLib Wrappers ==  ==  Asynchronous Method Calls Using GLib Wrappers ==




liox_lang_valid: /* Asynchronous Method Calls Using Stubs */
liox_lang_valid — Wed, 16 Sep 2009 08:40:16 GMT
Asynchronous Method Calls Using Stubs

		
		
		
		
		
		
		← Older revision
		Revision as of 08:40, 16 September 2009
		
		Line 99:
Line 99:
 ==  Asynchronous Method Calls Using Stubs ==  ==  Asynchronous Method Calls Using Stubs ==
  
- When the glib-bindings-tool is run, it will already generate the necessary wrapping stubs to support launching asynchronous method calls. What is then left to do is implementing the callback functions correctly, processing the return errors and launching the method call. glib-dbus-async/client-stubs.c + When the glib-bindings-tool is run, it already generates the necessary wrapping stubs to support launching asynchronous method calls. What is then left to do is implementing the callback functions correctly, processing the return errors and launching the method call. glib-dbus-async/client-stubs.c
  
   <tt><span>''<span><font color="#9A1900">/* Pull in the client stubs that were generated with</font></span>''</span>    <tt><span>''<span><font color="#9A1900">/* Pull in the client stubs that were generated with</font></span>''</span>
Line 108:
Line 108:
  
   <tt><span>''<span><font color="#9A1900">/**</font></span>''</span>    <tt><span>''<span><font color="#9A1900">/**</font></span>''</span>
-   <span>''<span><font color="#9A1900"> * This function will be called when the async setvalue1 will either</font></span>''</span> +   <span>''<span><font color="#9A1900"> * This function is called when the async setvalue1 either</font></span>''</span>
-   <span>''<span><font color="#9A1900"> * complete, timeout or fail (our server however does not signal</font></span>''</span> +   <span>''<span><font color="#9A1900"> * completes, timeouts or fails (our server however does not signal</font></span>''</span>
-   <span>''<span><font color="#9A1900"> * errors, but the client D-Bus library might). When this example</font></span>''</span> +   <span>''<span><font color="#9A1900"> * errors, but the client D-Bus library can do that). When this example</font></span>''</span>
-   <span>''<span><font color="#9A1900"> * program is left running for a while, you will see all three cases.</font></span>''</span> +   <span>''<span><font color="#9A1900"> * program is left running for a while, you can see all three cases.</font></span>''</span>
   <span>''<span><font color="#9A1900"> *</font></span>''</span>    <span>''<span><font color="#9A1900"> *</font></span>''</span>
   <span>''<span><font color="#9A1900"> * The prototype must match the one generated by the dbus-binding-tool</font></span>''</span>    <span>''<span><font color="#9A1900"> * The prototype must match the one generated by the dbus-binding-tool</font></span>''</span>
   <span>''<span><font color="#9A1900"> * (org_maemo_Value_setvalue1_reply).</font></span>''</span>    <span>''<span><font color="#9A1900"> * (org_maemo_Value_setvalue1_reply).</font></span>''</span>
   <span>''<span><font color="#9A1900"> *</font></span>''</span>    <span>''<span><font color="#9A1900"> *</font></span>''</span>
-   <span>''<span><font color="#9A1900"> * Since there is no return value from the RPC, the only useful</font></span>''</span> +   <span>''<span><font color="#9A1900"> * Because there is no return value from the RPC, the only useful</font></span>''</span>
-   <span>''<span><font color="#9A1900"> * parameter that we get is the error object, which we'll check.</font></span>''</span> +   <span>''<span><font color="#9A1900"> * parameter that we get is the error object, which we check.</font></span>''</span>
   <span>''<span><font color="#9A1900"> * If error is NULL, that means no error. Otherwise the RPC call</font></span>''</span>    <span>''<span><font color="#9A1900"> * If error is NULL, that means no error. Otherwise the RPC call</font></span>''</span>
   <span>''<span><font color="#9A1900"> * failed and we should check what the cause was.</font></span>''</span>    <span>''<span><font color="#9A1900"> * failed and we should check what the cause was.</font></span>''</span>
Line 127:
Line 127:
     <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>error <span><font color="#990000"><nowiki>!=</nowiki></font></span> NULL<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>      <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>error <span><font color="#990000"><nowiki>!=</nowiki></font></span> NULL<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>
       <span>'''<span><font color="#000000">g_printerr</font></span>'''</span><span><font color="#990000">(</font></span>PROGNAME <span><font color="#FF0000">"       ERROR: %s</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">,</font></span> error<span><font color="#990000">-&gt;</font></span>message<span><font color="#990000">);</font></span>        <span>'''<span><font color="#000000">g_printerr</font></span>'''</span><span><font color="#990000">(</font></span>PROGNAME <span><font color="#FF0000">"       ERROR: %s</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">,</font></span> error<span><font color="#990000">-&gt;</font></span>message<span><font color="#990000">);</font></span>
-       <span>''<span><font color="#9A1900">/* We need to release the error object since the stub code does</font></span>''</span> +       <span>''<span><font color="#9A1900">/* We need to release the error object because the stub code does</font></span>''</span>
   <span>''<span><font color="#9A1900">       not do it automatically. */</font></span>''</span>    <span>''<span><font color="#9A1900">       not do it automatically. */</font></span>''</span>
       <span>'''<span><font color="#000000">g_error_free</font></span>'''</span><span><font color="#990000">(</font></span>error<span><font color="#990000">);</font></span>        <span>'''<span><font color="#000000">g_error_free</font></span>'''</span><span><font color="#990000">(</font></span>error<span><font color="#990000">);</font></span>
Line 135:
Line 135:
   <span><font color="#FF0000">}</font></span></tt>    <span><font color="#FF0000">}</font></span></tt>
  
- Since the method call does not return any data, the parameters for the callback are at minimum (those three will always be received). Handling errors must be performed within the callback, since errors could be delayed from the server, and not visible immediately at launch time. N.B. The callback will not terminate the program on errors. This is done on purpose in order to demonstrate some common asynchronous problems below. The timestamp function is a small utility function to return a pointer to a string, representing the number of seconds since the program started (useful to visualize the order of the different asynchronous events below). glib-dbus-async/client-stubs.c + Because the method call does not return any data, the parameters for the callback are at minimum (those three are always received). Handling errors must be performed within the callback, because errors could be delayed from the server, and not visible immediately at launch time.
  +  
  + Note that the callback does not terminate the program on errors. This is done on purpose in order to demonstrate some common asynchronous problems below. The timestamp function is a small utility function to return a pointer to a string, representing the number of seconds because the program started (useful to visualize the order of the different asynchronous events below). glib-dbus-async/client-stubs.c
  
   <tt><span>''<span><font color="#9A1900">/**</font></span>''</span>    <tt><span>''<span><font color="#9A1900">/**</font></span>''</span>
-   <span>''<span><font color="#9A1900"> * This function will be called repeatedly from within the mainloop</font></span>''</span> +   <span>''<span><font color="#9A1900"> * This function is called repeatedly from within the mainloop</font></span>''</span>
   <span>''<span><font color="#9A1900"> * timer launch code.</font></span>''</span>    <span>''<span><font color="#9A1900"> * timer launch code.</font></span>''</span>
   <span>''<span><font color="#9A1900"> *</font></span>''</span>    <span>''<span><font color="#9A1900"> *</font></span>''</span>
-   <span>''<span><font color="#9A1900"> * It will launch asynchronous RPC method to set value1 with ever</font></span>''</span> +   <span>''<span><font color="#9A1900"> * It launches asynchronous RPC method to set value1 with ever</font></span>''</span>
   <span>''<span><font color="#9A1900"> * increasing argument.</font></span>''</span>    <span>''<span><font color="#9A1900"> * increasing argument.</font></span>''</span>
   <span>''<span><font color="#9A1900"> */</font></span>''</span>    <span>''<span><font color="#9A1900"> */</font></span>''</span>
Line 150:
Line 152:
         
     <span>''<span><font color="#9A1900">/* Start the RPC.</font></span>''</span>      <span>''<span><font color="#9A1900">/* Start the RPC.</font></span>''</span>
-   <span>''<span><font color="#9A1900">     This is done by calling the stub function that will take the new</font></span>''</span> +   <span>''<span><font color="#9A1900">     This is done by calling the stub function that takes the new</font></span>''</span>
   <span>''<span><font color="#9A1900">     value and the callback function to call on reply getting back.</font></span>''</span>    <span>''<span><font color="#9A1900">     value and the callback function to call on reply getting back.</font></span>''</span>
         
-   <span>''<span><font color="#9A1900">     The stub returns a DBusGProxyCall object, but we don't need it</font></span>''</span> +   <span>''<span><font color="#9A1900">     The stub returns a DBusGProxyCall object, but we do not need it</font></span>''</span>
-   <span>''<span><font color="#9A1900">     so we'll ignore the return value. The return value could be used</font></span>''</span> +   <span>''<span><font color="#9A1900">     so we ignore the return value. The return value could be used</font></span>''</span>
   <span>''<span><font color="#9A1900">     to cancel a pending request (from client side) with</font></span>''</span>    <span>''<span><font color="#9A1900">     to cancel a pending request (from client side) with</font></span>''</span>
   <span>''<span><font color="#9A1900">     dbus_g_proxy_cancel_call. We could also pass a pointer to</font></span>''</span>    <span>''<span><font color="#9A1900">     dbus_g_proxy_cancel_call. We could also pass a pointer to</font></span>''</span>
-   <span>''<span><font color="#9A1900">     user-data (last parameter), but we don't need one in this example.</font></span>''</span> +   <span>''<span><font color="#9A1900">     user-data (last parameter), but we do not need one in this example.</font></span>''</span>
-   <span>''<span><font color="#9A1900">     It would normally be used to "carry around" the application state.</font></span>''</span> +   <span>''<span><font color="#9A1900">     It is normally used to "carry around" the application state.</font></span>''</span>
   <span>''<span><font color="#9A1900">     */</font></span>''</span>    <span>''<span><font color="#9A1900">     */</font></span>''</span>
     <span>'''<span><font color="#000000">g_print</font></span>'''</span><span><font color="#990000">(</font></span>PROGNAME <span><font color="#FF0000">":%s:timerCallback launching setvalue1</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">,</font></span>      <span>'''<span><font color="#000000">g_print</font></span>'''</span><span><font color="#990000">(</font></span>PROGNAME <span><font color="#FF0000">":%s:timerCallback launching setvalue1</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">,</font></span>
Line 174:
Line 176:
   <span><font color="#FF0000">}</font></span></tt>    <span><font color="#FF0000">}</font></span></tt>
  
- Using the stub code is rather simple. For each generated synchronous version of a method wrapper, there will also be a _async version of the call. The main difference with the parameters is the removal of the GError pointer (since errors will be handled in the callback), and the addition of the callback function to use when the method completes, times out or encounters an error. + Using the stub code is rather simple. For each generated synchronous version of a method wrapper, there is also the a _async version of the call. The main difference with the parameters is the removal of the GError pointer (because errors are handled in the callback), and the addition of the callback function to use when the method completes, times out or encounters an error.
  
- The main function remains the same from the previous client examples (a once-per-second timer will be created and run from the mainloop, until the program is terminated). + The main function remains the same from the previous client examples (a once-per-second timer is created and run from the mainloop until the program is terminated).
  
 ==  Problems with Asynchronicity ==  ==  Problems with Asynchronicity ==




liox_lang_valid: /* Slow Test Server */
liox_lang_valid — Wed, 16 Sep 2009 08:34:03 GMT
Slow Test Server

		
		
		
		
		
		
		← Older revision
		Revision as of 08:34, 16 September 2009
		
		Line 28:
Line 28:
     <span>'''<span><font color="#000000">dbg</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Delaying operation"</font></span><span><font color="#990000">);</font></span>      <span>'''<span><font color="#000000">dbg</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Delaying operation"</font></span><span><font color="#990000">);</font></span>
     <span>'''<span><font color="#000000">g_usleep</font></span>'''</span><span><font color="#990000">(</font></span>SERVER_DELAY_USEC<span><font color="#990000">);</font></span>      <span>'''<span><font color="#000000">g_usleep</font></span>'''</span><span><font color="#990000">(</font></span>SERVER_DELAY_USEC<span><font color="#990000">);</font></span>
-     <span>''<span><font color="#9A1900">/* Compare the current value against old one. If they're the same,</font></span>''</span> +     <span>''<span><font color="#9A1900">/* Compare the current value against old one. If they are the same,</font></span>''</span>
-   <span>''<span><font color="#9A1900">     we don't need to do anything (except return success). */</font></span>''</span> +   <span>''<span><font color="#9A1900">     we do not need to do anything (except return success). */</font></span>''</span>
     <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>obj<span><font color="#990000">-&gt;</font></span>value1 <span><font color="#990000"><nowiki>!=</nowiki></font></span> valueIn<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span></tt>      <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>obj<span><font color="#990000">-&gt;</font></span>value1 <span><font color="#990000"><nowiki>!=</nowiki></font></span> valueIn<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span></tt>
  
- Building the server is done as before, but we'll notice the delay when we call an RPC method: + Building the server is done as before, but we notice the delay when we call an RPC method:
  
 <div class="graybox">  <div class="graybox">
Line 62:
Line 62:
 </div>  </div>
  
- In the example above, the time shell built-in command was used. It will run the given command while measuring the wall clock time (a.k.a. real time), and time used while executing the code and system calls. In this case, only the real time is of any interest. The method call will delay for about 5 seconds, as it should. The delay (even if given with microsecond resolution) is always approximate, and longer than the requested amount. Exact delay will depend on many factors, most of which cannot be directly influenced. + In the example above, the time shell built-in command was used. It runs the given command while measuring the wall clock time (the real time) and the time used while executing the code and system calls. In this case, only the real time is of any interest. The method call delays for about 5 seconds, as it should. The delay (even when given with microsecond resolution) is always approximate, and longer than the requested amount. Exact delay depends on many factors, most of which cannot be directly influenced.
  
 The next experiment deals with a likely scenario, where another method call comes along while the first one is still being executed. This is best tested by just repeating the sending command twice, but running the first one on the background (so that the shell does not wait for it to complete first). The server is still running on the background from the previous test:  The next experiment deals with a likely scenario, where another method call comes along while the first one is still being executed. This is best tested by just repeating the sending command twice, but running the first one on the background (so that the shell does not wait for it to complete first). The server is still running on the background from the previous test:
Line 93:
Line 93:
 </div>  </div>
  
- What can be seen from the above output is that the first client is delayed for about 5 seconds, while the second client (which was launched shortly after the first) is already delayed by a much longer period. This is to be expected, as the server can only process one request at a time, and will delay each request by 5 seconds. + What can be seen from the above output is that the first client is delayed for about 5 seconds, while the second client (which was launched shortly after the first) is already delayed by a much longer period. This is to be expected, as the server can only process one request at a time and delays each request by 5 seconds.
  
- Some server concurrency issues will be covered later, but for now, it is necessary that the clients are able to continue their "normal work" while they wait for the response from the server. Since this is just example code, "normal work" for our clients would be just waiting for the response, while blocking on incoming events (converted into callbacks). However, if the example programs were graphical, the asynchronous approach would make it possible for them to react to user input. D-Bus by itself does not support cancellation of method calls, once processing has started on the server side, so adding cancellation support would require a separate method call to the server. Since the server only handles one operation at a time, the current server cannot support method call cancellations at all. + The clients must be able to continue their "normal work" while they wait for the response from the server. Since this is just example code, "normal work" for the clients is waiting for the response while blocking on incoming events (converted into callbacks). However, if the example programs are graphical, the asynchronous approach make it possible for them to react to user input. D-Bus by itself does not support cancellation of method calls, once processing has started on the server side, so adding cancellation support requires a separate method call to the server. Since the server only handles one operation at a time, the current server cannot support method call cancellations at all.
  
 ==  Asynchronous Method Calls Using Stubs ==  ==  Asynchronous Method Calls Using Stubs ==

← Older revision		Revision as of 11:31, 6 September 2010
Line 320:		Line 320:
	== Asynchronous Method Calls Using GLib Wrappers ==		== Asynchronous Method Calls Using GLib Wrappers ==

-	Sometimes the interface XML is missing, so the dbus-bindings-tool cannot be run to generate the stub code. The GLib wrappers are generic enough to enable building own method calls, when necessary.	+	Sometimes the interface XML is missing, so the <code>dbus-bindings-tool</code> cannot be run to generate the stub code. The GLib wrappers are generic enough to enable building own method calls, when necessary.

	Starting with some known generated stub code to see which parts can possibly be reused with some modifications is usually the easiest solution. This is shown in the last step of this example, in order to make a version of the asynchronous client that works without the stub generator.		Starting with some known generated stub code to see which parts can possibly be reused with some modifications is usually the easiest solution. This is shown in the last step of this example, in order to make a version of the asynchronous client that works without the stub generator.

← Older revision		Revision as of 10:29, 6 September 2010
Line 1:		Line 1:
-	The example code used below can be found in the [~~https~~://~~garage~~.maemo.org/svn/maemoexamples/trunk/glib-dbus-~~signals~~/ garage svn].	+	The example code used below can be found in the [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/ garage svn].

	== Asynchronicity in D-Bus clients ==		== Asynchronicity in D-Bus clients ==
Line 13:		Line 13:
	== Slow Test Server ==		== Slow Test Server ==

-	The only change on the server side is the addition of delays into each of the RPC methods (<code>setvalue1</code>, <code>setvalue2</code>, <code>getvalue1</code> and <code>getvalue2</code>). This delay is added to the start of each function as follows: glib-dbus-async/server.c	+	The only change on the server side is the addition of delays into each of the RPC methods (<code>setvalue1</code>, <code>setvalue2</code>, <code>getvalue1</code> and <code>getvalue2</code>). This delay is added to the start of each function as follows: [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/server.c glib-dbus-async/server.c]

	<source lang="c">		<source lang="c">
Line 95:		Line 95:
	== Asynchronous Method Calls Using Stubs ==		== Asynchronous Method Calls Using Stubs ==

-	When the <code>glib-bindings-tool</code> is run, it already generates the necessary wrapping stubs to support launching asynchronous method calls. What is then left to do is implementing the callback functions correctly, processing the return errors and launching the method call. glib-dbus-async/client-stubs.c	+	When the <code>glib-bindings-tool</code> is run, it already generates the necessary wrapping stubs to support launching asynchronous method calls. What is then left to do is implementing the callback functions correctly, processing the return errors and launching the method call. [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/client-stubs.c glib-dbus-async/client-stubs.c]

	<source lang="c">		<source lang="c">
Line 103:		Line 103:
	</source>		</source>

-	The client has been simplified, so that it now only operates on <code>value1</code>. The callback that is called from the stub code is presented next: glib-dbus-async/client-stubs.c	+	The client has been simplified, so that it now only operates on <code>value1</code>. The callback that is called from the stub code is presented next: [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/client-stubs.c glib-dbus-async/client-stubs.c]

	<source lang="c">		<source lang="c">
Line 137:		Line 137:
	Because the method call does not return any data, the parameters for the callback are at minimum (those three are always received). Handling errors must be performed within the callback, because errors could be delayed from the server, and not visible immediately at launch time.		Because the method call does not return any data, the parameters for the callback are at minimum (those three are always received). Handling errors must be performed within the callback, because errors could be delayed from the server, and not visible immediately at launch time.

-	Note that the callback does not terminate the program on errors. This is done on purpose in order to demonstrate some common asynchronous problems below. The timestamp function is a small utility function to return a pointer to a string, representing the number of seconds because the program started (useful to visualize the order of the different asynchronous events below). glib-dbus-async/client-stubs.c	+	Note that the callback does not terminate the program on errors. This is done on purpose in order to demonstrate some common asynchronous problems below. The timestamp function is a small utility function to return a pointer to a string, representing the number of seconds because the program started (useful to visualize the order of the different asynchronous events below). [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/client-stubs.c glib-dbus-async/client-stubs.c]

	<source lang="c">		<source lang="c">
Line 178:		Line 178:
	</source>		</source>

-	Using the stub code is rather simple. For each generated synchronous version of a method wrapper, there is also the a _async version of the call. The main difference with the parameters is the removal of the <code>GError</code> pointer (because errors are handled in the callback), and the addition of the callback function to use when the method completes, times out or encounters an error.	+	Using the stub code is rather simple. For each generated synchronous version of a method wrapper, there is also the a <code>_async</code> version of the call. The main difference with the parameters is the removal of the <code>GError</code> pointer (because errors are handled in the callback), and the addition of the callback function to use when the method completes, times out or encounters an error.

	The main function remains the same from the previous client examples (a once-per-second timer is created and run from the mainloop until the program is terminated).		The main function remains the same from the previous client examples (a once-per-second timer is created and run from the mainloop until the program is terminated).
Line 324:		Line 324:
	Starting with some known generated stub code to see which parts can possibly be reused with some modifications is usually the easiest solution. This is shown in the last step of this example, in order to make a version of the asynchronous client that works without the stub generator.		Starting with some known generated stub code to see which parts can possibly be reused with some modifications is usually the easiest solution. This is shown in the last step of this example, in order to make a version of the asynchronous client that works without the stub generator.

-	The first step is to take a peek at the stub-generated code for the <code>setvalue1</code> call (when used asynchronously): glib-dbus-async/value-client-stub.h	+	The first step is to take a peek at the stub-generated code for the <code>setvalue1</code> call (when used asynchronously): [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/value-client-stub.h glib-dbus-async/value-client-stub.h]

	<source lang="c">		<source lang="c">
Line 362:		Line 362:
	</source>		</source>

-	What is notable in the code snippet above is that the _async method creates a temporary small structure that holds the pointer to the callback function and a copy of the userdata pointer. This small structure is then passed to <code>dbus_g_proxy_begin_call</code>, along with the address of the generated callback wrapper function (<code>org_maemo_Value_setvalue1_async_callback</code>). The GLib async launcher also takes a function pointer to a function to be used when the supplied "user-data" (in this case, the small structure) needs to be disposed of after the call. Because it uses <code>g_new</code> to allocate the small structure, it passes <code>g_free</code> as the freeing function. Next comes the argument specification for the method call, which obeys the same rules as the LibOSSO ones.	+	What is notable in the code snippet above is that the <code>_async</code> method creates a temporary small structure that holds the pointer to the callback function and a copy of the userdata pointer. This small structure is then passed to <code>dbus_g_proxy_begin_call</code>, along with the address of the generated callback wrapper function (<code>org_maemo_Value_setvalue1_async_callback</code>). The GLib async launcher also takes a function pointer to a function to be used when the supplied "user-data" (in this case, the small structure) needs to be disposed of after the call. Because it uses <code>g_new</code> to allocate the small structure, it passes <code>g_free</code> as the freeing function. Next comes the argument specification for the method call, which obeys the same rules as the LibOSSO ones.

	On RPC completion, the generated callback is invoked and it gets the real callback function pointer and the userdata as its "user-data" parameter. Firs it collects the exit code for the call with <code>dbus_g_proxy_end_call</code>, unpacks the data and invokes the real callback. After returning, the GLib wrappers (which called the generated callback) calls g_free to release the small structure, and the whole RPC launch ends.		On RPC completion, the generated callback is invoked and it gets the real callback function pointer and the userdata as its "user-data" parameter. Firs it collects the exit code for the call with <code>dbus_g_proxy_end_call</code>, unpacks the data and invokes the real callback. After returning, the GLib wrappers (which called the generated callback) calls g_free to release the small structure, and the whole RPC launch ends.
Line 368:		Line 368:
	The next step is to re-implement pretty much the same logic, but also dispose of the small structure because the callback is implemented directly, not as a wrapper-callback (it also omits the need for one memory allocation and one free).		The next step is to re-implement pretty much the same logic, but also dispose of the small structure because the callback is implemented directly, not as a wrapper-callback (it also omits the need for one memory allocation and one free).

-	The first step for that is to implement the RPC asynchronous launch code: glib-dbus-async/client-glib.c	+	The first step for that is to implement the RPC asynchronous launch code: [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/client-glib.c glib-dbus-async/client-glib.c]

	<source lang="c">		<source lang="c">
Line 413:		Line 413:
	</source>		</source>

-	And the callback that is invoked on method call completion timeouts or errors: glib-dbus-async/client-glib.c	+	And the callback that is invoked on method call completion timeouts or errors: [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/client-glib.c glib-dbus-async/client-glib.c]

	<source lang="c">		<source lang="c">
Line 457:		Line 457:
	</source>		</source>

-	The generated stub code is no longer needed, so the dependency rules for the stubless GLib version are different: glib-dbus-async/Makefile	+	The generated stub code is no longer needed, so the dependency rules for the stubless GLib version are different: [http://vcs.maemo.org/svn/maemoexamples/trunk/glib-dbus-async/Makefile glib-dbus-async/Makefile]

	<source lang="make">		<source lang="make">

← Older revision		Revision as of 10:12, 6 September 2010
Line 1:		Line 1:
	The example code used below can be found in the [https://garage.maemo.org/svn/maemoexamples/trunk/glib-dbus-signals/ garage svn].		The example code used below can be found in the [https://garage.maemo.org/svn/maemoexamples/trunk/glib-dbus-signals/ garage svn].

-	== Asynchronicity in D-Bus clients ==	+	== Asynchronicity in D-Bus clients ==

	So far all the RPC method calls that have been implemented here have been "fast", meaning that their execution has not depended on an access to slow services or external resources. In real life, however, it is quite likely that some services cannot be provided immediately, but have to wait for some external service to complete, before completing the method call.		So far all the RPC method calls that have been implemented here have been "fast", meaning that their execution has not depended on an access to slow services or external resources. In real life, however, it is quite likely that some services cannot be provided immediately, but have to wait for some external service to complete, before completing the method call.

-	The GLib wrappers provide a version of making method calls, where the call is launched (almost) immediately, and a callback is executed when the method call returns (either with a return value or an error).	+	The [[Documentation/Maemo 5 Developer Guide/DBus/Using GLib Wrappers For D-Bus\|GLib wrappers]] provide a version of making method calls, where the call is launched (almost) immediately, and a callback is executed when the method call returns (either with a return value or an error).

	Using the asynchronous wrappers is important when the program needs to update some kind of status or be reactive to the user (via a GUI or other interface). Otherwise, the program would block waiting for the RPC method to return, and would not be able to refresh the GUI or screen when required. An alternative solution is to use separate threads that run the synchronous methods. However, if this solution is used, synchronization between threads can become an issue, and debugging threaded programs is much harder than debugging single-threaded ones. Furthermore, the implementation of threads might be suboptimal in some environments. For these reasons, the thread scenario is not covered in this guide.		Using the asynchronous wrappers is important when the program needs to update some kind of status or be reactive to the user (via a GUI or other interface). Otherwise, the program would block waiting for the RPC method to return, and would not be able to refresh the GUI or screen when required. An alternative solution is to use separate threads that run the synchronous methods. However, if this solution is used, synchronization between threads can become an issue, and debugging threaded programs is much harder than debugging single-threaded ones. Furthermore, the implementation of threads might be suboptimal in some environments. For these reasons, the thread scenario is not covered in this guide.

← Older revision		Revision as of 09:00, 17 August 2010
Line 178:		Line 178:
	</source>		</source>

-	Using the stub code is rather simple. For each generated synchronous version of a method wrapper, there is also the a _async version of the call. The main difference with the parameters is the removal of the GError pointer (because errors are handled in the callback), and the addition of the callback function to use when the method completes, times out or encounters an error.	+	Using the stub code is rather simple. For each generated synchronous version of a method wrapper, there is also the a _async version of the call. The main difference with the parameters is the removal of the <code>GError</code> pointer (because errors are handled in the callback), and the addition of the callback function to use when the method completes, times out or encounters an error.

	The main function remains the same from the previous client examples (a once-per-second timer is created and run from the mainloop until the program is terminated).		The main function remains the same from the previous client examples (a once-per-second timer is created and run from the mainloop until the program is terminated).

-	== Problems with Asynchronicity ==	+	== Problems with Asynchronicity ==

	When the simple test program is built and run, it can be seen that everything starts off quite well. But at some point, problems start to appear:		When the simple test program is built and run, it can be seen that everything starts off quite well. But at some point, problems start to appear:
Line 362:		Line 362:
	</source>		</source>

-	What is notable in the code snippet above is that the _async method creates a temporary small structure that holds the pointer to the callback function and a copy of the userdata pointer. This small structure is then passed to dbus_g_proxy_begin_call, along with the address of the generated callback wrapper function (org_maemo_Value_setvalue1_async_callback). The GLib async launcher also takes a function pointer to a function to be used when the supplied "user-data" (in this case, the small structure) needs to be disposed of after the call. Because it uses g_new to allocate the small structure, it passes g_free as the freeing function. Next comes the argument specification for the method call, which obeys the same rules as the LibOSSO ones.	+	What is notable in the code snippet above is that the _async method creates a temporary small structure that holds the pointer to the callback function and a copy of the userdata pointer. This small structure is then passed to <code>dbus_g_proxy_begin_call</code>, along with the address of the generated callback wrapper function (<code>org_maemo_Value_setvalue1_async_callback</code>). The GLib async launcher also takes a function pointer to a function to be used when the supplied "user-data" (in this case, the small structure) needs to be disposed of after the call. Because it uses <code>g_new</code> to allocate the small structure, it passes <code>g_free</code> as the freeing function. Next comes the argument specification for the method call, which obeys the same rules as the LibOSSO ones.

-	On RPC completion, the generated callback is invoked and it gets the real callback function pointer and the userdata as its "user-data" parameter. Firs it collects the exit code for the call with dbus_g_proxy_end_call, unpacks the data and invokes the real callback. After returning, the GLib wrappers (which called the generated callback) calls g_free to release the small structure, and the whole RPC launch ends.	+	On RPC completion, the generated callback is invoked and it gets the real callback function pointer and the userdata as its "user-data" parameter. Firs it collects the exit code for the call with <code>dbus_g_proxy_end_call</code>, unpacks the data and invokes the real callback. After returning, the GLib wrappers (which called the generated callback) calls g_free to release the small structure, and the whole RPC launch ends.

	The next step is to re-implement pretty much the same logic, but also dispose of the small structure because the callback is implemented directly, not as a wrapper-callback (it also omits the need for one memory allocation and one free).		The next step is to re-implement pretty much the same logic, but also dispose of the small structure because the callback is implemented directly, not as a wrapper-callback (it also omits the need for one memory allocation and one free).

← Older revision		Revision as of 12:06, 12 February 2010
Line 457:		Line 457:

	Since the example program logic has not changed from the previous version, testing client-glib is not presented here (it can of course be tested if so desired, because the source code contains the fully working program). This version of the client also launches the method calls without waiting for previous method calls to complete.		Since the example program logic has not changed from the previous version, testing client-glib is not presented here (it can of course be tested if so desired, because the source code contains the fully working program). This version of the client also launches the method calls without waiting for previous method calls to complete.
		+
		+	[[Category:Development]]
		+	[[Category:Documentation]]
		+	[[Category:Fremantle]]

← Older revision		Revision as of 08:53, 16 September 2009
Line 316:		Line 316:
	== Asynchronous Method Calls Using GLib Wrappers ==		== Asynchronous Method Calls Using GLib Wrappers ==

-	Sometimes the interface XML ~~will be~~ missing, so the dbus-bindings-tool cannot be run to generate the stub code. The GLib wrappers are generic enough to enable building own method calls, when necessary.	+	Sometimes the interface XML is missing, so the dbus-bindings-tool cannot be run to generate the stub code. The GLib wrappers are generic enough to enable building own method calls, when necessary.

-	~~It is often easiest to start~~ with some known generated stub code to see, which parts can possibly be reused with some modifications. This ~~is what~~ is shown in the last step of this example, in order to make a version of the asynchronous client that ~~will work~~ without the stub generator.	+	Starting with some known generated stub code to see which parts can possibly be reused with some modifications is usually the easiest solution. This is shown in the last step of this example, in order to make a version of the asynchronous client that works without the stub generator.

	The first step is to take a peek at the stub-generated code for the setvalue1 call (when used asynchronously): glib-dbus-async/value-client-stub.h		The first step is to take a peek at the stub-generated code for the setvalue1 call (when used asynchronously): glib-dbus-async/value-client-stub.h
Line 356:		Line 356:
	<span><font color="#FF0000">}</font></span></tt>		<span><font color="#FF0000">}</font></span></tt>

-	What is notable in the code snippet above is that the _async method ~~will create~~ a temporary small structure that ~~will hold~~ the pointer to the callback function, and a copy of the userdata pointer. This small structure ~~will~~ then be passed to dbus_g_proxy_begin_call, along with the address of the generated callback wrapper function (org_maemo_Value_setvalue1_async_callback). The GLib async launcher ~~will~~ also ~~take~~ a function pointer to a function to ~~use~~ when the supplied "user-data" (in this case, the small structure) ~~will need~~ to be disposed of after the call. ~~Since~~ it uses g_new to allocate the small structure, it passes g_free as the freeing function. Next comes the argument specification for the method call, which obeys the same rules as the LibOSSO ones ~~before~~.	+	What is notable in the code snippet above is that the _async method creates a temporary small structure that holds the pointer to the callback function and a copy of the userdata pointer. This small structure is then passed to dbus_g_proxy_begin_call, along with the address of the generated callback wrapper function (org_maemo_Value_setvalue1_async_callback). The GLib async launcher also takes a function pointer to a function to be used when the supplied "user-data" (in this case, the small structure) needs to be disposed of after the call. Because it uses g_new to allocate the small structure, it passes g_free as the freeing function. Next comes the argument specification for the method call, which obeys the same rules as the LibOSSO ones.

-	On RPC completion, the generated callback ~~will be~~ invoked, and it ~~will get~~ the real callback function pointer and the userdata as its "user-data" parameter. ~~It will first collect~~ the exit code for the call with dbus_g_proxy_end_call, ~~unpack~~ the data and ~~invoke~~ the real callback. After returning, the GLib wrappers (which called the generated callback) ~~will call~~ g_free to release the small structure, and the whole RPC launch ~~will end~~.	+	On RPC completion, the generated callback is invoked and it gets the real callback function pointer and the userdata as its "user-data" parameter. Firs it collects the exit code for the call with dbus_g_proxy_end_call, unpacks the data and invokes the real callback. After returning, the GLib wrappers (which called the generated callback) calls g_free to release the small structure, and the whole RPC launch ends.

-	The next step is to re-implement pretty much the same logic, but also dispose of the small structure~~, since~~ the callback ~~will be~~ implemented directly, not as a wrapper-callback (it also omits the need for one memory allocation and one free).	+	The next step is to re-implement pretty much the same logic, but also dispose of the small structure because the callback is implemented directly, not as a wrapper-callback (it also omits the need for one memory allocation and one free).

	The first step for that is to implement the RPC asynchronous launch code: glib-dbus-async/client-glib.c		The first step for that is to implement the RPC asynchronous launch code: glib-dbus-async/client-glib.c
Line 405:		Line 405:
	<span><font color="#FF0000">}</font></span></tt>		<span><font color="#FF0000">}</font></span></tt>

-	And the callback that ~~will be~~ invoked on method call completion, timeouts or errors: glib-dbus-async/client-glib.c	+	And the callback that is invoked on method call completion timeouts or errors: glib-dbus-async/client-glib.c

	<tt><span>''<span><font color="#9A1900">/**</font></span>''</span>		<tt><span>''<span><font color="#9A1900">/**</font></span>''</span>
-	<span>''<span><font color="#9A1900"> * This function ~~will be~~ called when the async setvalue1 ~~will~~ either</font></span>''</span>	+	<span>''<span><font color="#9A1900"> * This function is called when the async setvalue1 either</font></span>''</span>
-	<span>''<span><font color="#9A1900"> * ~~complete~~, ~~timeout~~ or ~~fail~~ (same as before). The main difference in</font></span>''</span>	+	<span>''<span><font color="#9A1900"> * completes, timeouts or fails (same as before). The main difference in</font></span>''</span>
	<span>''<span><font color="#9A1900"> * using GLib/D-Bus wrappers is that we need to "collect" the return</font></span>''</span>		<span>''<span><font color="#9A1900"> * using GLib/D-Bus wrappers is that we need to "collect" the return</font></span>''</span>
	<span>''<span><font color="#9A1900"> * value (or error). This is done with the _end_call function.</font></span>''</span>		<span>''<span><font color="#9A1900"> * value (or error). This is done with the _end_call function.</font></span>''</span>
Line 447:		Line 447:
	<span><font color="#FF0000">}</font></span></tt>		<span><font color="#FF0000">}</font></span></tt>

-	The generated stub code is no longer needed, so the dependency rules for the stubless GLib version ~~will also be somewhat~~ different: glib-dbus-async/Makefile	+	The generated stub code is no longer needed, so the dependency rules for the stubless GLib version are different: glib-dbus-async/Makefile

	<tt>client-glib<span><font color="#990000"><nowiki>:</nowiki></font></span> client-glib<span><font color="#990000">.</font></span>o		<tt>client-glib<span><font color="#990000"><nowiki>:</nowiki></font></span> client-glib<span><font color="#990000">.</font></span>o
Line 456:		Line 456:
	</tt>		</tt>

-	Since the example program logic has not changed from the previous version, testing client-glib is not presented here (it can of course be tested if so desired, ~~since~~ the source code contains the fully working program). This version of the client ~~will~~ also ~~launch~~ the method calls without waiting for previous method calls to complete.	+	Since the example program logic has not changed from the previous version, testing client-glib is not presented here (it can of course be tested if so desired, because the source code contains the fully working program). This version of the client also launches the method calls without waiting for previous method calls to complete.

← Older revision		Revision as of 08:47, 16 September 2009
Line 182:		Line 182:
	== Problems with Asynchronicity ==		== Problems with Asynchronicity ==

-	When the simple test program is built and run, it can be seen that everything starts off quite well. But at some point, problems ~~will~~ start to appear:	+	When the simple test program is built and run, it can be seen that everything starts off quite well. But at some point, problems start to appear:

	<code>[sbox-FREMANTLE_X86: /glib-dbus-async] > make client-stubs		<code>[sbox-FREMANTLE_X86: /glib-dbus-async] > make client-stubs
Line 302:		Line 302:
	...</code>		...</code>

-	What happens above is rather subtle. The timer callback in the client launches once per second and performs the RPC method launch. The server, however, still has the 5 second delay for each method call in it. ~~It can be seen that the~~ successive launches go on without any responses for a while. The first response comes back at about 6 seconds from the starting of the client. At this point, the server already has four other outstanding method calls that it has not handled. Slowly the method calls are accumulating at the server end, and it does not deal with them quickly enough to satisfy the client.	+	What happens above is rather subtle. The timer callback in the client launches once per second and performs the RPC method launch. The server, however, still has the 5 second delay for each method call in it. The successive launches go on without any responses for a while. The first response comes back at about 6 seconds from the starting of the client. At this point, the server already has four other outstanding method calls that it has not handled. Slowly the method calls are accumulating at the server end and it does not deal with them quickly enough to satisfy the client.

-	After about 30 seconds, ~~it can be seen how~~ the setValue1Completed callback is invoked, but the method call fails. This has managed to trigger the method call timeout mechanism. After this point, all the method calls that have accumulated into the server (into a message queue) ~~will~~ fail in the client, since they all ~~will now~~ return late, even if the server actually does handle them.	+	After about 30 seconds, the setValue1Completed callback is invoked, but the method call fails. This has managed to trigger the method call timeout mechanism. After this point, all the method calls that have accumulated into the server (into a message queue) fail in the client, since they all return late now, even if the server actually does handle them.

-	Once the client is terminated, ~~it can be seen that~~ the server is still happily continuing serving the requests, oblivious to the fact that there is no client to process the responses.	+	Once the client is terminated, the server is still happily continuing serving the requests, oblivious to the fact that there is no client to process the responses.

-	The above test demonstrates quite brutally that the services need to be designed properly, so that there is a clearly defined protocol what to do in case a method call is delayed. It is also advisable to design a notification protocol to tell clients that something has completed, instead of forcing them to time out. Using D-Bus signals is one way, ~~but it is necessary to take care~~ not ~~to generate signals,~~ when ~~tere~~ is ~~nothing~~ listening to them. This can be done by only sending signals when an long operation finishes (assuming this has been documented as part of the service description).	+	The above test demonstrates quite brutally that the services need to be designed properly, so that there is a clearly defined protocol what to do in case a method call is delayed. It is also advisable to design a notification protocol to tell clients that something has completed, instead of forcing them to time out. Using D-Bus signals is one way. However, signals must not be generated when nothing is listening to them. This can be done by only sending signals when a long operation finishes (assuming this has been documented as part of the service description).

-	One partial fix ~~would be~~ for the client to track and make sure that only one method call to one service is outstanding at any given time. So, instead of just blindly launching the RPC methods, it should defer from launching, if it has not yet received a response from the server (and the call has not timed out).	+	One partial fix is for the client to track and make sure that only one method call to one service is outstanding at any given time. So, instead of just blindly launching the RPC methods, the client should defer from launching RPC methods if it has not yet received a response from the server (and the call has not timed out).

-	However, this fix is not complete, ~~since~~ the same problem ~~will manifest~~ itself once there are multiple clients running in parallel and requesting the same methods. The proper fix is to make the server capable of serving multiple requests in parallel~~. Some hints on how to do this are presented later on~~.	+	However, this fix is not complete, because the same problem manifests itself once there are multiple clients running in parallel and requesting the same methods. The proper fix is to make the server capable of serving multiple requests in parallel.

	== Asynchronous Method Calls Using GLib Wrappers ==		== Asynchronous Method Calls Using GLib Wrappers ==

← Older revision		Revision as of 08:40, 16 September 2009
Line 99:		Line 99:
	== Asynchronous Method Calls Using Stubs ==		== Asynchronous Method Calls Using Stubs ==

-	When the glib-bindings-tool is run, it ~~will~~ already ~~generate~~ the necessary wrapping stubs to support launching asynchronous method calls. What is then left to do is implementing the callback functions correctly, processing the return errors and launching the method call. glib-dbus-async/client-stubs.c	+	When the glib-bindings-tool is run, it already generates the necessary wrapping stubs to support launching asynchronous method calls. What is then left to do is implementing the callback functions correctly, processing the return errors and launching the method call. glib-dbus-async/client-stubs.c

	<tt><span>''<span><font color="#9A1900">/* Pull in the client stubs that were generated with</font></span>''</span>		<tt><span>''<span><font color="#9A1900">/* Pull in the client stubs that were generated with</font></span>''</span>
Line 108:		Line 108:

	<tt><span>''<span><font color="#9A1900">/**</font></span>''</span>		<tt><span>''<span><font color="#9A1900">/**</font></span>''</span>
-	<span>''<span><font color="#9A1900"> * This function ~~will be~~ called when the async setvalue1 ~~will~~ either</font></span>''</span>	+	<span>''<span><font color="#9A1900"> * This function is called when the async setvalue1 either</font></span>''</span>
-	<span>''<span><font color="#9A1900"> * ~~complete~~, ~~timeout~~ or ~~fail~~ (our server however does not signal</font></span>''</span>	+	<span>''<span><font color="#9A1900"> * completes, timeouts or fails (our server however does not signal</font></span>''</span>
-	<span>''<span><font color="#9A1900"> * errors, but the client D-Bus library ~~might~~). When this example</font></span>''</span>	+	<span>''<span><font color="#9A1900"> * errors, but the client D-Bus library can do that). When this example</font></span>''</span>
-	<span>''<span><font color="#9A1900"> * program is left running for a while, you ~~will~~ see all three cases.</font></span>''</span>	+	<span>''<span><font color="#9A1900"> * program is left running for a while, you can see all three cases.</font></span>''</span>
	<span>''<span><font color="#9A1900"> *</font></span>''</span>		<span>''<span><font color="#9A1900"> *</font></span>''</span>
	<span>''<span><font color="#9A1900"> * The prototype must match the one generated by the dbus-binding-tool</font></span>''</span>		<span>''<span><font color="#9A1900"> * The prototype must match the one generated by the dbus-binding-tool</font></span>''</span>
	<span>''<span><font color="#9A1900"> * (org_maemo_Value_setvalue1_reply).</font></span>''</span>		<span>''<span><font color="#9A1900"> * (org_maemo_Value_setvalue1_reply).</font></span>''</span>
	<span>''<span><font color="#9A1900"> *</font></span>''</span>		<span>''<span><font color="#9A1900"> *</font></span>''</span>
-	<span>''<span><font color="#9A1900"> * ~~Since~~ there is no return value from the RPC, the only useful</font></span>''</span>	+	<span>''<span><font color="#9A1900"> * Because there is no return value from the RPC, the only useful</font></span>''</span>
-	<span>''<span><font color="#9A1900"> * parameter that we get is the error object, which we~~'ll~~ check.</font></span>''</span>	+	<span>''<span><font color="#9A1900"> * parameter that we get is the error object, which we check.</font></span>''</span>
	<span>''<span><font color="#9A1900"> * If error is NULL, that means no error. Otherwise the RPC call</font></span>''</span>		<span>''<span><font color="#9A1900"> * If error is NULL, that means no error. Otherwise the RPC call</font></span>''</span>
	<span>''<span><font color="#9A1900"> * failed and we should check what the cause was.</font></span>''</span>		<span>''<span><font color="#9A1900"> * failed and we should check what the cause was.</font></span>''</span>
Line 127:		Line 127:
	<span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>error <span><font color="#990000"><nowiki>!=</nowiki></font></span> NULL<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>		<span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>error <span><font color="#990000"><nowiki>!=</nowiki></font></span> NULL<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span>
	<span>'''<span><font color="#000000">g_printerr</font></span>'''</span><span><font color="#990000">(</font></span>PROGNAME <span><font color="#FF0000">" ERROR: %s</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">,</font></span> error<span><font color="#990000">-></font></span>message<span><font color="#990000">);</font></span>		<span>'''<span><font color="#000000">g_printerr</font></span>'''</span><span><font color="#990000">(</font></span>PROGNAME <span><font color="#FF0000">" ERROR: %s</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">,</font></span> error<span><font color="#990000">-></font></span>message<span><font color="#990000">);</font></span>
-	<span>''<span><font color="#9A1900">/* We need to release the error object ~~since~~ the stub code does</font></span>''</span>	+	<span>''<span><font color="#9A1900">/* We need to release the error object because the stub code does</font></span>''</span>
	<span>''<span><font color="#9A1900"> not do it automatically. */</font></span>''</span>		<span>''<span><font color="#9A1900"> not do it automatically. */</font></span>''</span>
	<span>'''<span><font color="#000000">g_error_free</font></span>'''</span><span><font color="#990000">(</font></span>error<span><font color="#990000">);</font></span>		<span>'''<span><font color="#000000">g_error_free</font></span>'''</span><span><font color="#990000">(</font></span>error<span><font color="#990000">);</font></span>
Line 135:		Line 135:
	<span><font color="#FF0000">}</font></span></tt>		<span><font color="#FF0000">}</font></span></tt>

-	~~Since~~ the method call does not return any data, the parameters for the callback are at minimum (those three ~~will~~ always be received). Handling errors must be performed within the callback, ~~since~~ errors could be delayed from the server, and not visible immediately at launch time. ~~N.B. The~~ callback ~~will~~ not terminate the program on errors. This is done on purpose in order to demonstrate some common asynchronous problems below. The timestamp function is a small utility function to return a pointer to a string, representing the number of seconds ~~since~~ the program started (useful to visualize the order of the different asynchronous events below). glib-dbus-async/client-stubs.c	+	Because the method call does not return any data, the parameters for the callback are at minimum (those three are always received). Handling errors must be performed within the callback, because errors could be delayed from the server, and not visible immediately at launch time.
		+
		+	Note that the callback does not terminate the program on errors. This is done on purpose in order to demonstrate some common asynchronous problems below. The timestamp function is a small utility function to return a pointer to a string, representing the number of seconds because the program started (useful to visualize the order of the different asynchronous events below). glib-dbus-async/client-stubs.c

	<tt><span>''<span><font color="#9A1900">/**</font></span>''</span>		<tt><span>''<span><font color="#9A1900">/**</font></span>''</span>
-	<span>''<span><font color="#9A1900"> * This function ~~will be~~ called repeatedly from within the mainloop</font></span>''</span>	+	<span>''<span><font color="#9A1900"> * This function is called repeatedly from within the mainloop</font></span>''</span>
	<span>''<span><font color="#9A1900"> * timer launch code.</font></span>''</span>		<span>''<span><font color="#9A1900"> * timer launch code.</font></span>''</span>
	<span>''<span><font color="#9A1900"> *</font></span>''</span>		<span>''<span><font color="#9A1900"> *</font></span>''</span>
-	<span>''<span><font color="#9A1900"> * It ~~will launch~~ asynchronous RPC method to set value1 with ever</font></span>''</span>	+	<span>''<span><font color="#9A1900"> * It launches asynchronous RPC method to set value1 with ever</font></span>''</span>
	<span>''<span><font color="#9A1900"> * increasing argument.</font></span>''</span>		<span>''<span><font color="#9A1900"> * increasing argument.</font></span>''</span>
	<span>''<span><font color="#9A1900"> */</font></span>''</span>		<span>''<span><font color="#9A1900"> */</font></span>''</span>
Line 150:		Line 152:

	<span>''<span><font color="#9A1900">/* Start the RPC.</font></span>''</span>		<span>''<span><font color="#9A1900">/* Start the RPC.</font></span>''</span>
-	<span>''<span><font color="#9A1900"> This is done by calling the stub function that ~~will take~~ the new</font></span>''</span>	+	<span>''<span><font color="#9A1900"> This is done by calling the stub function that takes the new</font></span>''</span>
	<span>''<span><font color="#9A1900"> value and the callback function to call on reply getting back.</font></span>''</span>		<span>''<span><font color="#9A1900"> value and the callback function to call on reply getting back.</font></span>''</span>

-	<span>''<span><font color="#9A1900"> The stub returns a DBusGProxyCall object, but we ~~don't~~ need it</font></span>''</span>	+	<span>''<span><font color="#9A1900"> The stub returns a DBusGProxyCall object, but we do not need it</font></span>''</span>
-	<span>''<span><font color="#9A1900"> so we~~'ll~~ ignore the return value. The return value could be used</font></span>''</span>	+	<span>''<span><font color="#9A1900"> so we ignore the return value. The return value could be used</font></span>''</span>
	<span>''<span><font color="#9A1900"> to cancel a pending request (from client side) with</font></span>''</span>		<span>''<span><font color="#9A1900"> to cancel a pending request (from client side) with</font></span>''</span>
	<span>''<span><font color="#9A1900"> dbus_g_proxy_cancel_call. We could also pass a pointer to</font></span>''</span>		<span>''<span><font color="#9A1900"> dbus_g_proxy_cancel_call. We could also pass a pointer to</font></span>''</span>
-	<span>''<span><font color="#9A1900"> user-data (last parameter), but we ~~don't~~ need one in this example.</font></span>''</span>	+	<span>''<span><font color="#9A1900"> user-data (last parameter), but we do not need one in this example.</font></span>''</span>
-	<span>''<span><font color="#9A1900"> It ~~would~~ normally be used to "carry around" the application state.</font></span>''</span>	+	<span>''<span><font color="#9A1900"> It is normally used to "carry around" the application state.</font></span>''</span>
	<span>''<span><font color="#9A1900"> */</font></span>''</span>		<span>''<span><font color="#9A1900"> */</font></span>''</span>
	<span>'''<span><font color="#000000">g_print</font></span>'''</span><span><font color="#990000">(</font></span>PROGNAME <span><font color="#FF0000">":%s:timerCallback launching setvalue1</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">,</font></span>		<span>'''<span><font color="#000000">g_print</font></span>'''</span><span><font color="#990000">(</font></span>PROGNAME <span><font color="#FF0000">":%s:timerCallback launching setvalue1</font></span><span><font color="#CC33CC">\n</font></span><span><font color="#FF0000">"</font></span><span><font color="#990000">,</font></span>
Line 174:		Line 176:
	<span><font color="#FF0000">}</font></span></tt>		<span><font color="#FF0000">}</font></span></tt>

-	Using the stub code is rather simple. For each generated synchronous version of a method wrapper, there ~~will~~ also be a _async version of the call. The main difference with the parameters is the removal of the GError pointer (~~since~~ errors ~~will be~~ handled in the callback), and the addition of the callback function to use when the method completes, times out or encounters an error.	+	Using the stub code is rather simple. For each generated synchronous version of a method wrapper, there is also the a _async version of the call. The main difference with the parameters is the removal of the GError pointer (because errors are handled in the callback), and the addition of the callback function to use when the method completes, times out or encounters an error.

-	The main function remains the same from the previous client examples (a once-per-second timer ~~will be~~ created and run from the mainloop, until the program is terminated).	+	The main function remains the same from the previous client examples (a once-per-second timer is created and run from the mainloop until the program is terminated).

	== Problems with Asynchronicity ==		== Problems with Asynchronicity ==

← Older revision		Revision as of 08:34, 16 September 2009
Line 28:		Line 28:
	<span>'''<span><font color="#000000">dbg</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Delaying operation"</font></span><span><font color="#990000">);</font></span>		<span>'''<span><font color="#000000">dbg</font></span>'''</span><span><font color="#990000">(</font></span><span><font color="#FF0000">"Delaying operation"</font></span><span><font color="#990000">);</font></span>
	<span>'''<span><font color="#000000">g_usleep</font></span>'''</span><span><font color="#990000">(</font></span>SERVER_DELAY_USEC<span><font color="#990000">);</font></span>		<span>'''<span><font color="#000000">g_usleep</font></span>'''</span><span><font color="#990000">(</font></span>SERVER_DELAY_USEC<span><font color="#990000">);</font></span>
-	<span>''<span><font color="#9A1900">/* Compare the current value against old one. If they~~'re~~ the same,</font></span>''</span>	+	<span>''<span><font color="#9A1900">/* Compare the current value against old one. If they are the same,</font></span>''</span>
-	<span>''<span><font color="#9A1900"> we ~~don't~~ need to do anything (except return success). */</font></span>''</span>	+	<span>''<span><font color="#9A1900"> we do not need to do anything (except return success). */</font></span>''</span>
	<span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>obj<span><font color="#990000">-></font></span>value1 <span><font color="#990000"><nowiki>!=</nowiki></font></span> valueIn<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span></tt>		<span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>obj<span><font color="#990000">-></font></span>value1 <span><font color="#990000"><nowiki>!=</nowiki></font></span> valueIn<span><font color="#990000">)</font></span> <span><font color="#FF0000">{</font></span></tt>

-	Building the server is done as before, but we~~'ll~~ notice the delay when we call an RPC method:	+	Building the server is done as before, but we notice the delay when we call an RPC method:

	<div class="graybox">		<div class="graybox">
Line 62:		Line 62:
	</div>		</div>

-	In the example above, the time shell built-in command was used. It ~~will run~~ the given command while measuring the wall clock time (~~a.k.a.~~ real time), and time used while executing the code and system calls. In this case, only the real time is of any interest. The method call ~~will delay~~ for about 5 seconds, as it should. The delay (even if given with microsecond resolution) is always approximate, and longer than the requested amount. Exact delay ~~will depend~~ on many factors, most of which cannot be directly influenced.	+	In the example above, the time shell built-in command was used. It runs the given command while measuring the wall clock time (the real time) and the time used while executing the code and system calls. In this case, only the real time is of any interest. The method call delays for about 5 seconds, as it should. The delay (even when given with microsecond resolution) is always approximate, and longer than the requested amount. Exact delay depends on many factors, most of which cannot be directly influenced.

	The next experiment deals with a likely scenario, where another method call comes along while the first one is still being executed. This is best tested by just repeating the sending command twice, but running the first one on the background (so that the shell does not wait for it to complete first). The server is still running on the background from the previous test:		The next experiment deals with a likely scenario, where another method call comes along while the first one is still being executed. This is best tested by just repeating the sending command twice, but running the first one on the background (so that the shell does not wait for it to complete first). The server is still running on the background from the previous test:
Line 93:		Line 93:
	</div>		</div>

-	What can be seen from the above output is that the first client is delayed for about 5 seconds, while the second client (which was launched shortly after the first) is already delayed by a much longer period. This is to be expected, as the server can only process one request at a time, and ~~will delay~~ each request by 5 seconds.	+	What can be seen from the above output is that the first client is delayed for about 5 seconds, while the second client (which was launched shortly after the first) is already delayed by a much longer period. This is to be expected, as the server can only process one request at a time and delays each request by 5 seconds.

-	~~Some server concurrency issues will~~ be ~~covered later, but for now, it is necessary that the clients are~~ able to continue their "normal work" while they wait for the response from the server. Since this is just example code, "normal work" for ~~our~~ clients ~~would be just~~ waiting for the response, while blocking on incoming events (converted into callbacks). However, if the example programs ~~were~~ graphical, the asynchronous approach ~~would~~ make it possible for them to react to user input. D-Bus by itself does not support cancellation of method calls, once processing has started on the server side, so adding cancellation support ~~would require~~ a separate method call to the server. Since the server only handles one operation at a time, the current server cannot support method call cancellations at all.	+	The clients must be able to continue their "normal work" while they wait for the response from the server. Since this is just example code, "normal work" for the clients is waiting for the response while blocking on incoming events (converted into callbacks). However, if the example programs are graphical, the asynchronous approach make it possible for them to react to user input. D-Bus by itself does not support cancellation of method calls, once processing has started on the server side, so adding cancellation support requires a separate method call to the server. Since the server only handles one operation at a time, the current server cannot support method call cancellations at all.

	== Asynchronous Method Calls Using Stubs ==		== Asynchronous Method Calls Using Stubs ==