1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="orte-examples">
3 <title>ORTE Examples</title>
6 This chapter expect that you are familiar with RTPS communication
7 architecture described in <xref linkend="orte-description"/>.
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.
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, ...).
29 <figure id="cap:orte_pub_snapshots">
30 <title>Periodic Snapshots of a BestEffort Publisher
34 <imagedata align="center" fileref="&orte_pub_snapshots_img;"
35 format="EPS" scale="55" srccredit="OCERA CTU 2004" />
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.
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.
55 <section id="orte-example1">
56 <title>BestEffort Communication</title>
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:
65 int main(int argc, char *argv[])
68 ORTEBoolean suspended= ORTE_FALSE;
72 d = ORTEDomainAppCreate(ORTE_DEFAUL_DOMAIN, NULL, NULL, suspended);
75 printf("ORTEDomainAppCreate failed\n");
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>.
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.
96 ORTETypeRegisterAdd(d, "HelloMsg", NULL, NULL, 64);
100 To create a publication in specific domain use the function
101 ORTEPublicationCreate.
104 char instance2send[64];
105 NtpTime persistence, delay;
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 "Example HelloMsg",
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.
129 void sendCallBack(const ORTESendInfo *info, void *vinstance, void *sendCallBackParam)
131 char *instance = (char *) vinstance;
132 switch (info->status)
135 printf("Sending publication, count %d\n", counter);
136 sprintf(instance, "Hello world (%d)", counter++);
139 case CQL: //criticalQueueLevel has been reached
146 Subscribing application needs to create a subscription with
147 publication's Topic and TypeName. A callback function will be then
148 called when a new issue from publisher will be received.
152 NtpTime deadline, minimumSeparation;
154 NTPTIME_BUILD(deadline, 20);
155 NTPTIME_BUILD(minimumSeparation, 0);
156 p = ORTESubscriptionCreate( d,
159 "Example HelloMsg",
163 &minimumSeparation,
169 The callback function is shown in the following example:
172 void recvCallBack(const ORTERecvInfo *info, void *vinstance, void *recvCallBackParam)
174 char *instance = (char *) vinstance;
175 switch (info->status)
178 printf("%s\n", instance);
181 case DEADLINE: //deadline occurred
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.
197 <section id="orte-example2">
198 <title>Reliable communication</title>
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
206 The creation of reliable communication starts like besteffort communication.
207 Difference is in creation a subscription. Third parameter is just only changed
213 NtpTime deadline, minimumSeparation;
215 NTPTIME_BUILD(deadline, 20);
216 NTPTIME_BUILD(minimumSeparation, 0);
217 p = ORTESubscriptionCreate( d,
220 "Example HelloMsg",
224 &minimumSeparation,
229 <para><phrase role="strong">Note:</phrase></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).
236 Sending of a data is blocking operation. It's strongly recommended to
237 setup sending queue to higher value. Default value is 1.
242 ORTEPublicationPropertiesGet(publisher,pp);
243 pp->sendQueueSize=10;
244 pp->criticalQueueLevel=8;
245 ORTEPublicationPropertiesSet(publisher,pp);
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.
256 <section id="orte-example3">
257 <title>Serialization/Deserialization</title>
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.
266 typedef struct BoxType {
272 BoxTypeSerialize(CDR_Codec *cdrCodec, void *instance) {
273 BoxType *boxType=(BoxType*)instance;
275 CDR_put_long(cdrCodec,boxType->color);
276 CDR_put_long(cdrCodec,boxType->shape);
280 BoxTypeDeserialize(CDR_Codec *cdrCodec, void *instance) {
281 BoxType *boxType=(BoxType*)instance;
283 CDR_get_long(cdrCodec,&boxType->color);
284 CDR_get_long(cdrCodec,&boxType->shape);
289 When we have written a serialization/deserialization routine we need to
290 register this routines to midleware by function
291 <function>ORTETypeRegisterAdd</function>
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>).
310 All of codes are part of the Shapedemo located in subdirectory
311 <filename>orte/contrib/shape</filename>.