doc/orte/orte_examples.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <section id="orte-examples">
   3   <title>ORTE Examples</title>
   4
   5   <para>
   6   This chapter expect that you are familiar with RTPS communication
   7   architecture described in <xref linkend="orte-description"/>.
   8   </para>
   9   <para>
  10   Publications can offer multiple reliability policies ranging from
  11   best-efforts to strict (blocking) reliability. Subscription can
  12   request multiple policies of desired reliability and specify the
  13   relative precedence of each policy. Publications will automatically
  14   select among the highest precedence requested policy that is
  15   offered by the publication.
  16   </para>
  17
  18   <itemizedlist>
  19     <listitem>
  20       <para>
  21       <emphasis role="bold">BestEffort:</emphasis>
  22       This reliability policy is suitable for data that are sending
  23       with a period.  There are no message resending when a message is lost.
  24       On other hand, this policy offer maximal predictable behaviour.
  25       For instance, consider a publication which send data from a sensor
  26       (pressure, temperature, ...).
  27       </para>
  28
  29       <figure id="cap:orte_pub_snapshots">
  30         <title>Periodic Snapshots of a BestEffort Publisher
  31         </title>
  32         <mediaobject>
  33           <imageobject>
  34             <imagedata align="center" fileref="&orte_pub_snapshots_img;"
  35               format="EPS" scale="35" srccredit="OCERA CTU 2004" />
  36           </imageobject>
  37         </mediaobject>
  38       </figure>
  39
  40     </listitem>
  41     <listitem>
  42       <para>
  43       <emphasis role="bold">StrictReliable:</emphasis>
  44       The ORTE supports the reliable delivery of issues. This kind of communication
  45       is used where a publication want to be sure that all data will be delivered to
  46       subscriptions.  For instance, consider a publication which send commands.
  47       </para>
  48       <para>
  49       Command data flow requires that each instruction in the sequence is
  50       delivered reliably once and only once. Commands are often not time critical.
  51       </para>
  52     </listitem>
  53   </itemizedlist>
  54
  55   <section id="orte-example1">
  56     <title>BestEffort Communication</title>
  57
  58   <para>
  59   Before creating a Publication or Subscription is necessary to
  60   create a domain by using function
  61   <parameter class='function'>ORTEDomainAppCreate</parameter>.
  62   The code should looks like:
  63   </para>
  64   <programlisting>
  65 int main(int argc, char *argv[])
  66 {
  67   ORTEDomain *d = NULL;
  68   ORTEBoolean suspended= ORTE_FALSE;
  69
  70   ORTEInit();
  71
  72   d = ORTEDomainAppCreate(ORTE_DEFAUL_DOMAIN, NULL, NULL, suspended);
  73   if (!d)
  74   {
  75     printf(&#34;ORTEDomainAppCreate failed\n&#34;);
  76     return -1;
  77   }
  78 }
  79   </programlisting>
  80
  81   <para>
  82   The ORTEDomainAppCreate allocates and initializes resources that are needed
  83   for communication. The parameter <parameter class='command'>suspended</parameter> says
  84   if ORTEDomain takes suspend communicating threads. In
  85   positive case you have to start threads manually by using
  86   <parameter class='function'>ORTEDomainStart</parameter>.
  87   </para>
  88
  89
  90   <para>
  91   Next step in creation of a application is registration serialization and
  92   deserialization routines for the specific type. You can't specify this functions,
  93   but the incoming data will be only copied to output buffer.
  94   </para>
  95   <programlisting>
  96 ORTETypeRegisterAdd(d, &#34;HelloMsg&#34;, NULL, NULL, 64);
  97   </programlisting>
  98
  99   <para>
 100   To create a publication in specific domain use the function
 101   ORTEPublicationCreate.
 102   </para>
 103   <programlisting>
 104 char instance2send[64];
 105 NtpTime persistence, delay;
 106
 107 NTPTIME_BUILD(persistence, 3);  /* this issue is valid for 3 seconds */
 108 NTPTIME_DELAY(delay, 1);        /* a callback function will be called every 1 second */
 109 p = ORTEPublicationCreate( d,
 110                          &#34;Example HelloMsg&#34;,
 111                          &#34;HelloMsg&#34;,
 112                          &#38;instance2Send,
 113                          &#38;persistence,
 114                          1,
 115                          sendCallBack,
 116                          NULL,
 117                          &#38;delay);
 118   </programlisting>
 119
 120   <para>
 121   The callback function will be then called when a new issue from
 122   publisher has to be sent. It's the case when you specify callback routine in
 123   <parameter class='function'>ORTEPublicationCreate</parameter>. When
 124   there isn't a routine you have to send data manually by call function
 125   <parameter class='function'>ORTEPublicationSend</parameter>. This option
 126   is useful for sending periodic data.
 127   </para>
 128   <programlisting>
 129 void sendCallBack(const ORTESendInfo *info, void *vinstance, void *sendCallBackParam)
 130 {
 131   char *instance = (char *) vinstance;
 132   switch (info-&#62;status)
 133   {
 134     case NEED_DATA:
 135       printf(&#34;Sending publication, count %d\n&#34;, counter);
 136       sprintf(instance, &#34;Hello world (%d)&#34;, counter++);
 137       break;
 138
 139     case CQL:  //criticalQueueLevel has been reached
 140       break;
 141   }
 142 }
 143   </programlisting>
 144
 145   <para>
 146   Subscribing application needs to create a subscription with
 147   publication&#39;s Topic and TypeName. A callback function will be then
 148   called when a new issue from publisher will be received.
 149   </para>
 150   <programlisting>
 151 ORTESubscription *s;
 152 NtpTime deadline, minimumSeparation;
 153
 154 NTPTIME_BUILD(deadline, 20);
 155 NTPTIME_BUILD(minimumSeparation, 0);
 156 p = ORTESubscriptionCreate( d,
 157                           IMMEDIATE,
 158                           BEST_EFFORTS,
 159                           &#34;Example HelloMsg&#34;,
 160                           &#34;HelloMsg&#34;,
 161                           &#38;instance2Recv,
 162                           &#38;deadline,
 163                           &#38;minimumSeparation,
 164                           recvCallBack,
 165                           NULL);
 166    </programlisting>
 167
 168    <para>
 169    The callback function is shown in the following example:
 170    </para>
 171    <programlisting>
 172 void recvCallBack(const ORTERecvInfo *info, void *vinstance, void *recvCallBackParam)
 173 {
 174   char *instance = (char *) vinstance;
 175   switch (info-&#62;status)
 176   {
 177     case NEW_DATA:
 178       printf(&#34;%s\n&#34;, instance);
 179       break;
 180
 181     case DEADLINE:  //deadline occurred
 182       break;
 183   }
 184 }
 185     </programlisting>
 186
 187     <para>
 188     Similarly examples are located in ORTE subdirectory
 189     <filename>orte/examples/hello</filename>. There are
 190     demonstrating programs how to create an application
 191     which will publish some data and another application, which will
 192     subscribe to this publication.
 193     </para>
 194
 195   </section>
 196
 197   <section id="orte-example2">
 198     <title>Reliable communication</title>
 199
 200     <para>
 201     The reliable communication is used especially in situations
 202     where we need guarantee data delivery. The ORTE supports the inorder
 203     delivery of issues with built-in retry mechanism
 204     </para>
 205     <para>
 206     The creation of reliable communication starts like besteffort communication.
 207     Difference is in creation a subscription. Third parameter is just only changed
 208     to STRICT_RELIABLE.
 209     </para>
 210
 211   <programlisting>
 212 ORTESubscription *s;
 213 NtpTime deadline, minimumSeparation;
 214
 215 NTPTIME_BUILD(deadline, 20);
 216 NTPTIME_BUILD(minimumSeparation, 0);
 217 p = ORTESubscriptionCreate( d,
 218                           IMMEDIATE,
 219                           STRICT_RELIABLE,
 220                           &#34;Example HelloMsg&#34;,
 221                           &#34;HelloMsg&#34;,
 222                           &#38;instance2Recv,
 223                           &#38;deadline,
 224                           &#38;minimumSeparation,
 225                           recvCallBack,
 226                           NULL);
 227   </programlisting>
 228
 229   <para><phrase role="strong">Note:</phrase></para>
 230   <para>
 231   Strict reliable subscription must set minimumSeparation to zero! The middleware
 232   can't guarantee that the data will be delivered on first attempt (retry mechanism).
 233   </para>
 234
 235   <para>
 236   Sending of a data is blocking operation. It's strongly recommended to
 237   setup sending queue to higher value. Default value is 1.
 238   </para>
 239   <programlisting>
 240 ORTEPublProp *pp;
 241
 242 ORTEPublicationPropertiesGet(publisher,pp);
 243 pp->sendQueueSize=10;
 244 pp->criticalQueueLevel=8;
 245 ORTEPublicationPropertiesSet(publisher,pp);
 246   </programlisting>
 247
 248   <para>
 249   An example of reliable communication is in ORTE subdirectory
 250   <filename>orte/examples/reliable</filename>. There are located
 251   a strictreliable subscription and publication.
 252   </para>
 253
 254   </section>
 255
 256   <section id="orte-example3">
 257     <title>Serialization/Deserialization</title>
 258
 259     <para>
 260     Actually the ORTE doesn't support any automatic creation of
 261     serialization/deserializaction routines.
 262     This routines have to be designed manually by the user. In next is
 263     shown, how should looks both for the structure BoxType.
 264     </para>
 265 <programlisting>
 266 typedef struct BoxType {
 267     int32_t  color;
 268     int32_t  shape;
 269 } BoxType;
 270
 271 void
 272 BoxTypeSerialize(CDR_Codec *cdrCodec, void *instance) {
 273   BoxType  *boxType=(BoxType*)instance;
 274
 275   CDR_put_long(cdrCodec,boxType->color);
 276   CDR_put_long(cdrCodec,boxType->shape);
 277 }
 278
 279 void
 280 BoxTypeDeserialize(CDR_Codec *cdrCodec, void *instance) {
 281   BoxType  *boxType=(BoxType*)instance;
 282
 283   CDR_get_long(cdrCodec,&#38;boxType->color);
 284   CDR_get_long(cdrCodec,&#38;boxType->shape);
 285 }
 286 </programlisting>
 287
 288   <para>
 289   When we have written a serialization/deserialization routine we need to
 290   register this routines to midleware by function
 291   <function>ORTETypeRegisterAdd</function>
 292   </para>
 293
 294 <programlisting>
 295    ORTETypeRegisterAdd(
 296                 domain,
 297                 "BoxType",
 298                 BoxTypeSerialize,
 299                 BoxTypeDeserialize,
 300                 sizeof(BoxType));
 301 </programlisting>
 302
 303   <para>
 304   The registration must be called before creation a publication or subscription.
 305   Normally is <function>ORTETypeRegisterAdd</function> called immediately after
 306   creation of a domain (<function>ORTEDomainCreate</function>).
 307   </para>
 308
 309   <para>
 310   All of codes are part of the Shapedemo located in subdirectory
 311   <filename>orte/contrib/shape</filename>.
 312   </para>
 313   </section>
 314
 315 </section>