Replace socket_handler::fill_buffer() recursion with loop (#8389)
[libt2n] / doc / index.doc
CommitLineData
d321225e
JT
1/*! \mainpage libt2n - (talk to neighbor)
2 \section intro_sec Introduction
3e11fd2c
JT
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.
3e11fd2c 5 \par
1e1f17bf 6Using 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
3e11fd2c 7 \ref libt2n::connection "connections"
1e1f17bf 8 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)
3e11fd2c 9 \par
1e1f17bf 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.
3e11fd2c
JT
11 \par
12 The input for the code generator is standard C++ code
13 \ref notes4 "[4]"
14 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]").
b35406fe 15 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.
d321225e
JT
16 \par
17 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.
e8b2809d
JT
18 \section License
19 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.
20
d321225e
JT
21 \section install_sec Installation
22
23 \subsection requirements Requirements
3e11fd2c 24 \par libt2n
0a8803cc 25 - boost <http://www.boost.org/> (serialization <http://www.boost.org/libs/serialization/>)
3e11fd2c 26 \par libt2n-codegen
d321225e
JT
27 - gccxml <http://www.gccxml.org>
28 - libxmlpp <http://libxmlplusplus.sourceforge.net/>
0a8803cc
GE
29 \par client-wrapper
30 - boost <http://www.boost.org/> (bind <http://www.boost.org/libs/bind/>, function <http://www.boost.org/libs/function/>)
31 - gcc 4.1 or newer <http://gcc.gnu.org/>
d321225e
JT
32
33 \subsection recommended Recommended
34 - pkg-config <http://pkgconfig.freedesktop.org/wiki/>
3e11fd2c 35 - autotools (autoconf <http://www.gnu.org/software/autoconf/>, automake, libtool)
d321225e
JT
36
37 \subsection Compilation
38 \verbatim
3e11fd2c 39 ./configure && make check && make install
d321225e
JT
40 \endverbatim
41
42 \subsection Usage
de51cfa8 43 Take a look at the \ref example.
d321225e 44
1e1f17bf 45 \subsection Homepage
12fbab79 46 The libt2n homepage with downloads and further information can be found at <http://www.intra2net.com/en/developer/libt2n/>.
1e1f17bf 47
3e11fd2c
JT
48 \subsection References
49 - \anchor notes1
50 [1] inter-process communication (IPC), http://en.wikipedia.org/wiki/Inter-process_communication
51 - \anchor notes2
52 [2] remote procedure call (RPC), http://en.wikipedia.org/wiki/Remote_procedure_call and "THE RPC MODEL" http://www.faqs.org/rfcs/rfc1050.html
53 - \anchor notes3
9a5d7790 54 [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
3e11fd2c
JT
55 - \anchor notes4
56 [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
57 - \anchor notes5
58 [5] interface description language (IDL), http://en.wikipedia.org/wiki/Interface_description_language
59 - \anchor notes6
0a8803cc 60 [6] boost serialization, http://www.boost.org/libs/serialization/
d321225e 61*/
6e434d1f
JT
62
63/*! \page example Usage example
64
65 In this example we create two packages using the autotools:
66 - server program and client library to connect to the server. The server exports a simple procedure using one group: "t2nexample"
67 - client program using the library
68
69 \section server Example server program and client library
70
71 \par The procedure to export (input for the code generator - libt2n-codegen): t2nexample.cpp:
9a5d7790 72 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.
6e434d1f
JT
73 \include example1/t2nexample.cpp
74
75 \par Required includes go into the group header file: t2nexample.hxx:
e72e07f3 76 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.
6e434d1f
JT
77 \include example1/t2nexample.hxx
78
79 \par The server program: server.cpp:
1e1f17bf
GE
80 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
81tied to one command group. Which source file exports it's functions into which command group is defined in the Makefile (see below).
6e434d1f
JT
82 \include example1/server.cpp
83
84 \par Using autoconf and automake to build a example server program and a client library.
85 In the configure.in(.ac) we check for libt2n using the LIBT2N_CHECK m4 macro provided by libt2n.
86 \verbinclude example1/configure.in
87 Writing the Makefile.am isn't difficult either. We have to list the command groups used. For each command group we have to list the C++ source files with the procedures to export. For each group we build a client library by listing the generated client code (group_client.cpp) in a corresponding libtool library target. The .pc file for the library is generated automatically. The sources of the server program must include the generated server code (group_server.cpp), the file with the main entry point and of course the procedure definition.
88 \verbinclude example1/Makefile.am
89
90 \par Build and install the package
91 To build and install the package we first have to create the configure script and the other help scripts of the autotools by running autoreconf.
92 \verbatim
93 autoreconf -f -i && ./configure && make install
94 \endverbatim
95
96 \section client Client using the library
97 Using the library is as simple as using any other library using pkg-config (the pkg-config .pc file is created automatically by the included Makefile snippet)
98 \par We only have to check that the library is installed
99 \verbinclude example1-client/configure.in
100 \par The Makefile.am needs nothing special
101 \verbinclude example1-client/Makefile.am
102 \par The client program: client.cpp:
103 The example client first connects to the local socket. The connection is passed to the constructor of the generated class. To call the remote procedure the "testfunc" method is called. The example first passes "throw" to the remote procedure which will result in a exception to be thrown which is passed back to the client and thrown on the client side again. In the example the exception is caught and it is checked whether the string returned by what() is correct. If so a second remote procedure call is made and its return value is checked. Only if both tests succeed the program will exit with a status value indicating success.
104 \include example1-client/client.cpp
105
106 \par Build and install the package
107 \verbatim
108 autoreconf -f -i && ./configure && make install
109 \endverbatim
110
111 \par Test
112 To test whether it works we first start the server that creates a socket 'socket' in the current working directory. Then we run the client and print "ok" if it exited with a status value indicating success.
113 \verbatim
114$ cd /tmp
115$ file socket
116socket: cannot open `socket' (No such file or directory)
117$ libt2n-example1-server &
118[1] 7711
119$ file socket
120socket: socket
121$ libt2n-example1-client && echo ok
122ok
123$ kill %1
124$ rm socket
125 \endverbatim
9a5d7790
GE
126
127 \section wrapper The Client-Wrapper
128 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
129 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
130 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
131 to execute any user-provided code before and after a call to the server is made.
132
133 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.
134
135 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.
136
137 This example shows how to use the Client-Wrapper:
138
139 \include example1-client-wrapper/client.cpp
140
141The 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.
142
6e434d1f 143*/