\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/>
- \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. It is marked for export with the attribute macro "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.
+ 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:
$ 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