developer.intra2net.com Git - libt2n/blob - doc/index.doc

   1 /*! \mainpage libt2n - (talk to neighbor)
   2  \section intro_sec Introduction
   3  \par
   4  libt2n (talk to neighbor) is a C++ library for inter-process communication (IPC \ref notes1 "[1]") with an additional code generator (libt2n-codegen) to make C++ remote procedure calls (RPC \ref notes2 "[2]")  simple.
   5   \htmlonly
   6   <p><img src="http://jan.netcomp.monash.edu.au/webservices/rpc_stub.png" alt="rpc"/></p>
   7   \endhtmlonly
   8  \par
   9  Figure: Remote procedure call overview \ref notes3 "[3]"
  10  \par
  11  The figure shows an general overview of the steps involved in a remote procedure call. Using libt2n and its code generator only the server procedure implementations have to be written manually. The stubs are generated by the code generator and the inter-process communication routines are provided by libt2n. libt2n provides an abstract interface for
  12         \ref libt2n::connection "connections"
  13  hiding the details of the concrete communication mechanism used. At the moment it is implemented for local sockets (a.k.a "Unix domain sockets") and TCP/IP sockets.
  14  \par
  15  The client procedure stubs provide an interface to the server procedure implementations. To call the server procedure the client stub procedure is called (step 1). The client stub procedure transforms the procedure arguments and signature including the procedure "name" into a sequence of bytes using boost serialization \ref notes6 "[6]". This byte sequence represents a request to call a procedure with those arguments (step 2). Using the communication routines of libt2n the request is sent to the server. (step 3,4). The server procedure stubs de-serialize the request and call the corresponding server procedure using the reconstructed arguments (step 5). The result of the server procedure is serialized and sent back to the client (steps 6,7,8). Finally the result is de-serialized on client side again and returned to the caller. (steps 9,10).
  16  \par
  17  The input for the code generator is standard C++ code
  18         \ref notes4 "[4]"
  19  and you mark the procedures you want to expose to other processes. Because the interface is described in C++ directly there is no need for a interface description language (IDL, \ref notes5 "[5]").
  20  The code generator is used to create the client and server stubs for the marked procedures. The procedures can be grouped and each group maps to two classes (cmd_group_... and cmd_group_..._client). The cmd_group_..._client class provides the interface to call remote procedures. Each remote procedure maps to a method of this class and the constructor takes a connection object establishing the binding to the remote side. For each group the code generator is called and generates 6 output files: group_common.hxx, group_common.cpp, group_client.hxx, group_client.cpp, group_server.hxx, group_server.cpp. The _common files are used by client and server whereas the _client files contain the client stub code (the cmd_group_..._client class) and the _server files the server stub code.
  21  \par
  22  To simplify the build process a Makefile snippet is provided that allows to create a server program and a client library (including a corresponding .pc file) using the autotools easily.
  23  \section License
  24  The libt2n libaray is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License version 2.1 as published by the Free Software Foundation. The code generator (libt2n-codegen) is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
  25
  26  \section install_sec Installation
  27
  28  \subsection requirements Requirements
  29  \par libt2n
  30  - boost <http://www.boost.org/> (serialization <http://www.boost.org/libs/serialization/doc/>)
  31  \par libt2n-codegen
  32  - gccxml <http://www.gccxml.org>
  33  - libxmlpp <http://libxmlplusplus.sourceforge.net/>
  34
  35  \subsection recommended Recommended
  36  - pkg-config <http://pkgconfig.freedesktop.org/wiki/>
  37  - autotools (autoconf <http://www.gnu.org/software/autoconf/>, automake, libtool)
  38
  39  \subsection Compilation
  40  \verbatim
  41  ./configure && make check && make install
  42  \endverbatim
  43
  44  \subsection Usage
  45  Take a look at the example file:../../../libt2n-examples/doc/html/index.html
  46
  47  \subsection References
  48  - \anchor notes1
  49  [1] inter-process communication (IPC), http://en.wikipedia.org/wiki/Inter-process_communication
  50  - \anchor notes2
  51  [2] remote procedure call (RPC), http://en.wikipedia.org/wiki/Remote_procedure_call and "THE RPC MODEL" http://www.faqs.org/rfcs/rfc1050.html
  52  - \anchor notes3
  53  [3] Figure: Remote procedure call overview, http://jan.netcomp.monash.edu.au/webservices/rpc_stub.png, Jan Newmarch "Web services" http://jan.netcomp.monash.edu.au/webservices/tutorial.html
  54  - \anchor notes4
  55  [4] in fact gccxml is used to parse the C++ code and the XML output of gccxml is used as input for the code generator
  56  - \anchor notes5
  57  [5] interface description language (IDL), http://en.wikipedia.org/wiki/Interface_description_language
  58  - \anchor notes6
  59  [6] boost serialization, http://www.boost.org/libs/serialization/doc/
  60 */