\section intro_sec Introduction
\par
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.
- \htmlonly
- <p><img src="http://jan.netcomp.monash.edu.au/webservices/rpc_stub.png" alt="rpc"/></p>
- \endhtmlonly
\par
- Figure: Remote procedure call overview \ref notes3 "[3]"
- \par
- 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
+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
\ref libt2n::connection "connections"
- 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.
+ 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-sockets. (\ref libt2n::socket_client_connection, \ref libt2n::socket_server_connection)
\par
- 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).
+ The client procedure stubs provide an interface to the server procedure implementations. To call the server procedure the client stub procedure is called. 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). Using the communication routines of libt2n the request is sent to the server. The server procedure stubs de-serialize the request and call the corresponding server procedure using the reconstructed arguments. The result of the server procedure is serialized and sent back to the client. Finally the result is de-serialized on client side again and returned to the caller.
\par
The input for the code generator is standard C++ code
\ref notes4 "[4]"
\subsection requirements Requirements
\par libt2n
- - boost <http://www.boost.org/> (serialization <http://www.boost.org/libs/serialization/doc/>)
+ - boost <http://www.boost.org/> (serialization <http://www.boost.org/libs/serialization/>)
\par libt2n-codegen
- gccxml <http://www.gccxml.org>
- libxmlpp <http://libxmlplusplus.sourceforge.net/>
+ \par client-wrapper
+ - boost <http://www.boost.org/> (bind <http://www.boost.org/libs/bind/>, function <http://www.boost.org/libs/function/>)
+ - gcc 4.1 or newer <http://gcc.gnu.org/>
\subsection recommended Recommended
- pkg-config <http://pkgconfig.freedesktop.org/wiki/>
\subsection Usage
Take a look at the \ref example.
+ \subsection Homepage
+ The libt2n homepage with downloads and further information can be found at <http://www.intra2net.com/en/developer/libt2n/>.
+
\subsection References
- \anchor notes1
[1] inter-process communication (IPC), http://en.wikipedia.org/wiki/Inter-process_communication
- \anchor notes2
[2] remote procedure call (RPC), http://en.wikipedia.org/wiki/Remote_procedure_call and "THE RPC MODEL" http://www.faqs.org/rfcs/rfc1050.html
- \anchor notes3
- [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
+ [3] Figure: Remote procedure call overview, http://jan.newmarch.name/webservices/rpc_stub.png , Jan Newmarch "Web services" http://jan.newmarch.name/webservices/tutorial.html
- \anchor notes4
[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
- \anchor notes5
[5] interface description language (IDL), http://en.wikipedia.org/wiki/Interface_description_language
- \anchor notes6
- [6] boost serialization, http://www.boost.org/libs/serialization/doc/
+ [6] boost serialization, http://www.boost.org/libs/serialization/
*/
/*! \page example Usage example
\section server Example server program and client library
\par The procedure to export (input for the code generator - libt2n-codegen): t2nexample.cpp:
- First the procedure to export is defined. In this example the procedure throws an exception if the input string is "throw". The exception is passed back to the client transparently. Otherwise some text is appended and returned.
+ First the procedure to export is defined. It is marked for export with the attribute macro \ref LIBT2N_EXPORT. In this example the procedure throws an exception if the input string is "throw". The exception is passed back to the client transparently. Otherwise some text is appended and returned.
\include example1/t2nexample.cpp
\par Required includes go into the group header file: t2nexample.hxx:
- All includes required to get the declarations of the types used by the procedures to export go into the group header file. libt2n uses boost for serialization. This means all types involved in a remote procedure call must be boost serializable. In this example we only use std::string provided by <string> and boost already provides serialization for std::string in the boost/serialization/string.hpp header file.
+ All includes required to get the declarations of the types used by the procedures to export go into the group header file. libt2n uses boost for serialization. This means all types involved in a remote procedure call must be boost serializable. In this example we only use std::string provided by \<string\> and boost already provides serialization for std::string in the boost/serialization/string.hpp header file.
\include example1/t2nexample.hxx
\par The server program: server.cpp:
- We have to provide the main entry point for the server program. In this example we use a local socket and the server program simply waits until a request.is received which then is handled by the generated code directly.
+ We have to provide the main entry point for the server program. In this example we use a local socket and the server program simply waits until a request is received which then is handled by the generated code directly. We use a \ref libt2n::group_command_server to handle the requests. Each \ref libt2n::group_command_server is
+tied to one command group. Which source file exports it's functions into which command group is defined in the Makefile (see below).
\include example1/server.cpp
\par Using autoconf and automake to build a example server program and a client library.
$ kill %1
$ rm socket
\endverbatim
+
+ \section wrapper The Client-Wrapper
+ The interfaces can be called directly in the way outlined above. But this means you have to take care of connection errors between client and server
+ at each call, possibly try to reconnect and so on. Libt2n provides the Client-Wrapper to ease this. It is a way to select a error handling strategy
+ once and use it automatically for all calls invoked through the Wrapper. Tough error-handling is the common usecase, the Client-Wrapper could be used
+ to execute any user-provided code before and after a call to the server is made.
+
+ The other feature that the Client-Wrapper provides is a connection-singleton. T2n (currently) only offers single-threaded servers. So if you use methods of a T2n-server in a program, you usually only want to maintain one common connection to this server - even if it is accessed from different parts/modules/classes/... of your program. The Client-Wrapper is initialized with a \ref libt2n::ConnectionWrapper.
+
+ This \ref libt2n::ConnectionWrapper takes the error-handling strategy (e.g. reconnect-then-throw) and everything needed to establish a connection (e.g. socket name or host and tcp-port) as parameters. A connection is established at the first actual request to the server and re-used for following requests. You don't need to pass around client-handles and the like to your classes or methods, finding the right wrapper is done via the global singleton created for each server-interface initialized for the wrapper.
+
+ This example shows how to use the Client-Wrapper:
+
+ \include example1-client-wrapper/client.cpp
+
+The details of the Client-Wrapper can be found in the \ref libt2n::T2nSingletonWrapper, but beware, the code is full of ugly templates and template-construction-defines.
+
*/
git://developer.intra2net.com / libt2n / blobdiff