deep-shallow-api.sgml

机器人开源项目orocos的源代码

make them load binary code that provides new, or updates existing,
functionalities and behaviours.
The data that is communicated within the system in order to achieve
this (re)configuration is given the generic name of configuration
flow. Configuration is typically not realtime, but requires some
execution flow messages to bring the components to a
“configuration state”, where functionality can be unloaded
and loaded in a safe way.
</para>
<para>
Configuration flow methods typically 
<emphasis role="strong">apply to a whole application</emphasis>,
<emphasis>i.e.</emphasis> a set of cooperating components.
</para>
</listitem>
</itemizedlist>
The APIs for each of the three above-mentioned functionalities are very
different, and these 
<emphasis role="strong">APIs should not be mixed</emphasis>. This is
in accordance with the ideas behind 
<link linkend="deep-shallow">small and shallow interfaces</link>:
an application that provides data flow, execution flow as well as
configuration flow functionality should <emphasis>compose</emphasis>
its End User API from the separate data, execution and configuration
flow APIs.
</para>
<para>
Note that <link linkend="data-execution-configuration">Execution
flow and Configuration flow</link> methods are natural for
<ulink url="components-doc.html">components</ulink>, but exceptional
for class libraries. In addition, the different types of components
each have their own specific API methods. (See the above-mentioned
document for more details.)
</para>

</section>


<section id="multiple-dispatching">
<title>Multiple dispatching</title>
<para>
Multiple dispatching is a programming technique that fits very well
with (but is not a necessary nor sufficient condition for) shallow
APIs: its benefit is that it offers <emphasis>polymorphism</emphasis>
not only on the member function call, but also on the call's
<emphasis>arguments</emphasis>, but it comes with runtime overhead.
(<ulink url="http://jamesthornton.com/eckel/TIPatterns/html/Chapter12.html">This</ulink>
is one of the links with some more information.) For example,
multiple dispatching allows a generic motion call like
<programlisting>
 Move ( MyDevice, MyMotionGenerator, MyReferencePoint, MyController);
</programlisting>
where all of the arguments are specific implementation versions of the
general concepts of a device, a motion generator, a reference point
for which the motion is specified, and a controller with which to
execute the motion. Note that for all these arguments, also the
dimension of the motion (1D, 2D, 3D) need not be specified explicitly,
but can be checked at compile time.
</para>
<para>
Of course, there <emphasis>is</emphasis> overhead connected to
multiple dispatching, caused by the
<emphasis>run-time object inspection</emphasis> required 
to find out the actual type of the arguments and to select the
corresponding implementation. Hence, this technique is 
<emphasis role="strong">not very well suited</emphasis> for:
<itemizedlist>

<listitem>
<para>
<emphasis>Real-time algorithms</emphasis>, because of the
type-checking overhead.
</para>
</listitem>

<listitem>
<para>
<emphasis>Frequent calls on distributed objects</emphasis>, because
the &ldquo;inspection&rdquo; must travel back on forth over the
network for each argument of the method call, <emphasis>and</emphasis>
repeating the check for each of a series of identical calls is a waste
of time.
</para>
</listitem>

</itemizedlist>
<note>
<title>Orocos API choice</title>
<para>
Because of the run-time overhead, and the lack of support in many
programming languages, multiple dispatching will remain an exception
for most of the Orocos class libraries and components. It can be used
for non-realtime commands that users give to an
<emphasis>application</emphasis>.
</para>
<para>
One of the concrete consequences is that the same conceptual
functionality for 1D, 2D and 3D objects will be provided in separate
libraries, with extremely similar but nevertheless not completely
identical APIs.
</para>
</note>
</para>

</section>


<section id="interface-implementation">
<title>Interface semantics&mdash;Application families</title>

<para>
&orocos; has the ambitious goal to provide reusable software
components for <emphasis>all</emphasis> possible feedback control
applications. Reusability is facilitated a lot by consistency and
minimalism of the component APIs. One big step to achieve consistency
and minimalism is
<ulink url="decoupling.html">semantic decoupling</ulink>: applications
are put in <emphasis>families</emphasis>, such that: (i) all members in a 
family have the 
<emphasis role="strong">same interface semantics</emphasis>, and (ii)
members within a family are distinguished by the specific values of a
number of <emphasis role="strong">family properties</emphasis> (for
example, the geometrical and physical parameters of their mechanical
components). The 
<ulink url="kindyn-doc.html#SERIAL321">Serial321</ulink>
robots are an example of such an application family: they only differ
in their link lengths, their artificially defined zero positions, and
their base and end-effector frame positions.
</para>
<para>
&ldquo;Same interface semantics&rdquo; means that each member of
a family has exactly the same set of methods in its API, with the same
<emphasis>method name</emphasis>, the same
<emphasis>structure</emphasis> of arguments in the method prototype,
and the same <emphasis>argument names</emphasis>. In addition, the
<emphasis>effect</emphasis> of the method is the same for all members
in the family.
</para>
<para>
The concepts of <emphasis>interface semantics</emphasis> and
<emphasis>application family</emphasis> are straightforward to
generalize to one more level of abstraction: application families are
collected in &ldquo;meta-families&rdquo; in which each member-family
has <emphasis>formally</emphasis> the same API as all other
member-families, but (some of) the <emphasis>types</emphasis> of the
arguments in the method calls are different. These argument type
differences come from differences in:
<itemizedlist>

<listitem>
<para>
the <emphasis role="strong">dimension of the device space.</emphasis>
For example, all <emphasis>Serial</emphasis> robots form a
meta-family of devices with the same API, but different argument
types, <emphasis>i.c.</emphasis> the number of joints in their
kinematic chain.
</para>
</listitem>

<listitem>
<para>
the <emphasis role="strong">dimension of the task space.</emphasis>
For example, all <emphasis>constrained motion applications</emphasis> 
form a meta-family, where the different dimensions of the constrained
and free subspaces of the task space are reflected in some of the
method call arguments.
</para>
</listitem>

</itemizedlist>
</para>
<para>
Non-realtime components can use
<link linkend="multiple-dispatching">multiple dispatching</link>
to provide exactly the same API for a whole meta-family.
Realtime components must use alternative solutions:
<orderedlist>

<listitem>
<para>
<emphasis role="strong">Virtual interfaces</emphasis>, with
application-specific implementation through interface inheritance.
</para>
</listitem>

<listitem>
<para>
<emphasis role="strong">
 <ulink url="components-doc.html#SESSION-STATE">Session state</ulink>
</emphasis>: the arguments are
of the &ldquo;union&rdquo; type (in the sense of the C programming
language), and the session state indicates which interpretation of the
union is currently selected. (The session state is set via a method in
the <link linkend="data-execution-configuration">Execution flow</link>
API.)
</para>
</listitem>

</orderedlist>
<note>
<title>Orocos API choice</title>
<para> 
A multiple dispatching API is appropriate for
<emphasis>non-realtime components with low communication costs</emphasis>.
</para>
<para> 
The virtual interface API is the method of choice for
<emphasis>class libraries</emphasis>.
</para>
<para>
The session state-based API is only available to
<emphasis>components that have a session state</emphasis>.
</para>
</note>
</para>

</section>


</article>