<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"	"docbook/dtd/4.1/docbook.dtd" [<!ENTITY orocos "<acronym>Orocos</acronym>">]><article><articleinfo>   <title>Generic <emphasis>Application Programming Interface</emphasis> designissues  </title>  <author>    <firstname>Herman</firstname>    <surname>Bruyninckx</surname>    <affiliation>      <address>        Herman.Bruyninckx(at)mech.kuleuven.ac.be      </address>    </affiliation>  </author> <copyright>  <year>2003&ndash;2004</year>  <holder>Herman Bruyninckx &mdash;Permission is granted to copy, distribute and/or modify this documentunder the terms of the GNU General Public License(<ulink url="http://www.fsf.org/copyleft/gpl.html">http://www.fsf.org/copyleft/gpl.html</ulink>), where the <emphasis>source code</emphasis> of the document is the <ulink url="deep-shallow-api.xml">XML file</ulink>.</holder> </copyright> <revhistory>  <revision>    <revnumber>0.01</revnumber>    <date>June 29, 2003</date>    <authorinitials>HB</authorinitials>    <revremark>Initial draft.</revremark>   </revision>  <revision>    <revnumber>0.02</revnumber>    <date>July 7, 2003</date>    <authorinitials>HB</authorinitials>    <revremark>Added some remarks about &ldquo;multipledispatching&rdquo;.</revremark>   </revision>  <revision>    <revnumber>0.03</revnumber>    <date>July 13, 2003</date>    <authorinitials>HB</authorinitials>	 <revremark>Added introduction, a discussion about class and component APIs, andconcrete API suggestions.</revremark>   </revision>  <revision>    <revnumber>0.04</revnumber>    <date>March 21, 2004</date>    <authorinitials>HB</authorinitials>	 <revremark>Extended the Class vs. Component discussion.</revremark>   </revision>  <revision>    <revnumber>0.05</revnumber>    <date>April 17, 2004</date>    <authorinitials>HB</authorinitials>	 <revremark>Reworked all sections. Added section on data, execution andconfiguration flow API. Added section on interface semantics andapplication families. Outsourced the details of the discussion aboutclasses versus components to its own document. Removed the section onpush/pull.    </revremark>   </revision> </revhistory> <abstract> <para> <emphasis role="strong">Abstract</emphasis> </para> <para>This document discusses various issues that influence the design of aprogramming interface (API), and provides guidelines for how APIs arechosen in the Orocos project.  </para> </abstract></articleinfo> <para>Robotics and machine tools are typical<emphasis role="strong">integration</emphasis> application areas:their controllers are the result of a combination of servoroutines, kinematic routines, motion generation, hardware interfacingand event handling, command language interpretation, etc.The application programming interface (API) of such controllersinevitably becomes quite extensive, <emphasis>and</emphasis> thedesign and implementation of the whole system is necessarily a groupeffort, too big for one single programmer. </para><para>Hence, the designers and programmers need some guidelines on how todesign APIs. This documents discusses a number of relevant issues tokeep in mind when choosing an API.</para><section id="deep-shallow"><title> Deep vs. Shallow </title><para>This is a first distinction between two approaches to provide an API:<itemizedlist><listitem><para><emphasis role="strong">Deep API.</emphasis>Each specific robot or machine tool is a specialization of a genericclass, let's say &ldquo;<function>robot</function>&rdquo;. From thisgeneric class, one derives more concrete machine classes by<emphasis role="strong">inheritance</emphasis>. Everyinheritance step adds one or more specific properties, such as: thenumber of driven axes; the kind of motion generation used; etc.</para><para>This leads quickly to a very deep inheritance tree. And, in addition,this tree is very difficult to keep generally maintainable. Forexample, what would be the consequences on the API and on theinheritance tree of changing from a three axes machine to a five axesmachine, if the level at which the number of axes has&ldquo;entered&rdquo; the inheritance hierarchy is somewhere &ldquo;inthe middle&rdquo;? </para></listitem><listitem><para><emphasis role="strong">Shallow API.</emphasis>Each of the domains that are integrated into a robot controller getsits own class hierarchy, fully <emphasis>decoupled</emphasis> from theother domains. (<ulink url="decoupling.html">This document</ulink>gives more details about the meaning and importance of&ldquo;decoupling&rdquo;.)This approach has two consequences: the API for each domain is notvery deep (i.e., &ldquo;shallow&rdquo;), and the API for a specificmachine tool or robot is built by<emphasis role="strong">composition/aggregation</emphasis> of the APIs of the integrated domains.</para></listitem></itemizedlist><note><title>Orocos API choice</title><para> The complexity and variance of robotics and machine tool softwaresystems is such that deep APIs are not a good idea. And hence, most ofthe Orocos library/component APIs will be shallow.</para></note></para></section><section id="data-execution-configuration"><title>Data flow&mdash;Execution flow&mdash;Configuration flow</title><para>In a component-based software system, the components exchangeinformation in various ways and for various purposes. In the APIdesign process, it is useful to distinguish between threefundamentally different information exchange goals, which we call<emphasis role="strong">data flow</emphasis>,<emphasis role="strong">execution flow</emphasis>, and<emphasis role="strong">configuration flow</emphasis>:<itemizedlist><listitem><para><emphasis role="strong">Data flow</emphasis>is the task-specific information that componentsexchange between each other in a continuous (&ldquo;streaming&rdquo;)way, and which the components<emphasis role="strong">process</emphasis> with thefunctionality they have selected to run as the result of previousconfiguration flow and execution flow messages.</para><para>Data flow methods are<emphasis role="strong">traditional method calls</emphasis> onobjects: the method performs an &ldquo;operation&rdquo; on its inputsand generates the result as an output. So, the Data flow API shouldcontain <emphasis>only</emphasis> methods that fit in this category;all other types of functionality belongs to the Execution orConfiguration flow categories below.</para></listitem><listitem><para><emphasis role="strong">Execution flow</emphasis>.In many configurations of a component-based software system,components can<emphasis role="strong">change their functionality inrealtime</emphasis>, triggered byexecution flow data. Typically, the execution flow consists of eventsthat trigger a <emphasis role="strong">state machine</emphasis> in acomponent, and each state corresponds to a different functionality(&ldquo;input-output&rdquo; behaviour) of the component.</para><para>Execution flow generates &ldquo;state changes&rdquo;, and hence isbuilt on <emphasis role="strong">events</emphasis>. Note that theexact semantics of an execution flow action cannot be defined in theinternals of one single object: the result depends on the<emphasis>distributed reaction</emphasis> of many components.</para></listitem><listitem><para><emphasis role="strong">Configuration flow</emphasis>.From time to time, a (set of) components must be (re)configured, to