From 1e1f17bfc845a310878f49326fafa015ee36c698 Mon Sep 17 00:00:00 2001 From: Gerd v. Egidy Date: Thu, 21 Dec 2006 15:07:46 +0000 Subject: [PATCH] libt2n: (gerd) improve docu, cleanup for public release --- configure.in | 2 +- doc/Doxyfile.in | 2 +- doc/Makefile.am | 2 +- doc/header.html | 42 ++++++++++++++++++++++++++++++++++++++++++ doc/index.doc | 19 +++++++++---------- libt2n.spec.in | 7 ++++--- src/command_server.hxx | 5 ++++- src/container.hxx | 4 ++-- src/t2n_exception.hxx | 7 +++++-- 9 files changed, 69 insertions(+), 21 deletions(-) create mode 100644 doc/header.html diff --git a/configure.in b/configure.in index fe30057..41756f8 100644 --- a/configure.in +++ b/configure.in @@ -2,7 +2,7 @@ AC_INIT(configure.in) AM_CONFIG_HEADER(config.h) dnl AC_CONFIG_HEADERS([config.h:config.h.in]) -AM_INIT_AUTOMAKE(libt2n, 0.1) +AM_INIT_AUTOMAKE(libt2n, 0.2) AC_DEFINE(PROTOCOL_VERSION, 1, [protocol version used (integers, increase version if incompatible)]) diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 84f6970..60bc3f7 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -652,7 +652,7 @@ HTML_FILE_EXTENSION = .html # each generated HTML page. If it is left blank doxygen will generate a # standard header. -HTML_HEADER = +HTML_HEADER = header.html # The HTML_FOOTER tag can be used to specify a personal HTML footer for # each generated HTML page. If it is left blank doxygen will generate a diff --git a/doc/Makefile.am b/doc/Makefile.am index 01bc533..852d249 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -12,4 +12,4 @@ all: $(MANUALS) html/index.html: $(top_srcdir)/src/*.cpp $(top_srcdir)/src/*.hxx $(top_srcdir)/codegen/*.hxx $(top_srcdir)/codegen/*.cpp $(srcdir)/index.doc $(DOXYGEN) -EXTRA_DIST = index.doc +EXTRA_DIST = index.doc header.html diff --git a/doc/header.html b/doc/header.html new file mode 100644 index 0000000..203d62d --- /dev/null +++ b/doc/header.html @@ -0,0 +1,42 @@ + + +libt2n - (talk to neighbor) + + + + + + + + + + + +
+ + + + +
+
\ No newline at end of file diff --git a/doc/index.doc b/doc/index.doc index b94ca12..395603d 100644 --- a/doc/index.doc +++ b/doc/index.doc @@ -2,17 +2,12 @@ \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 -

rpc

- \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. (\ref libt2n::socket_client_connection, \ref libt2n::socket_server_connection) + 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]" @@ -44,6 +39,9 @@ \subsection Usage Take a look at the \ref example. + \subsection Homepage + The libt2n homepage with downloads and further information can be found at . + \subsection References - \anchor notes1 [1] inter-process communication (IPC), http://en.wikipedia.org/wiki/Inter-process_communication @@ -68,7 +66,7 @@ \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 "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: @@ -76,7 +74,8 @@ \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. diff --git a/libt2n.spec.in b/libt2n.spec.in index 07cb77d..ec48b7b 100644 --- a/libt2n.spec.in +++ b/libt2n.spec.in @@ -18,7 +18,7 @@ C++ IPC library %package devel Summary: talk2neighbor - C++ IPC library Group: Intranator/Development -Requires: libt2n = %{version} libgettext gccxml +Requires: libt2n = %{version} libgettext gccxml libxml++ BuildPrereq: boost-devel %description devel @@ -31,9 +31,9 @@ C++ IPC library devel files cp -f /usr/share/libtool/ltmain.sh . autoreconf --force --install ./configure $RPM_BUILD_WITH_OPTIMIZE --prefix=%{prefix} -dmake +make -dmake check +make check %install make DESTDIR=$RPM_BUILD_ROOT install @@ -50,6 +50,7 @@ rm -fr $RPM_BUILD_ROOT %{prefix}/lib/libt2n.so* %files devel +%doc doc examples examples-codegen %defattr(-,root,root) %{prefix}/bin/libt2n-codegen %{prefix}/lib/*.*a* diff --git a/src/command_server.hxx b/src/command_server.hxx index c86b285..be3a6ab 100644 --- a/src/command_server.hxx +++ b/src/command_server.hxx @@ -50,7 +50,10 @@ template struct Derived_from { Derived_from() { void(*p)(T*) = constraints; } }; -/// server handling group of incoming commands +/** @brief server handling group of incoming commands + + the template must be derived from libt2n::command. +*/ template class group_command_server : public command_server { diff --git a/src/container.hxx b/src/container.hxx index 710a07e..f869166 100644 --- a/src/container.hxx +++ b/src/container.hxx @@ -33,7 +33,7 @@ namespace libt2n { -/** @brief contains the result (return value or exception) of a executed command +/** @brief contains the result (return value as libt2n::result or an libt2n::t2n_exception) of a executed command */ class result_container { @@ -71,7 +71,7 @@ class result_container { return (result_type==regular); } }; -/** @brief contains a command +/** @brief contains a libt2n::command */ class command_container { diff --git a/src/t2n_exception.hxx b/src/t2n_exception.hxx index 14243fc..121d482 100644 --- a/src/t2n_exception.hxx +++ b/src/t2n_exception.hxx @@ -38,7 +38,10 @@ void serialize(Archive & ar, std::exception & g, const unsigned int version) namespace libt2n { -/// a generic exception that can be handeled with libt2n +/** @brief a generic exception that can be handeled with libt2n + @note don't derive the exceptions your application generates directly from this one + but use libt2n::t2n_runtime_error for this +*/ class t2n_exception : public std::exception { private: @@ -232,7 +235,7 @@ class t2n_serialization_error : public t2n_exception /** @brief a runtime error within the remote function. derive your own custom exceptions from this one - @note you must override the virtual clone method if you do (used by \ref command_server::handle_packet) + @note you must override the virtual clone method if you do so (used by libt2n::command_server::handle()) */ class t2n_runtime_error : public t2n_exception { -- 1.7.1