From: g0dil Date: Tue, 9 Jan 2007 13:12:46 +0000 (+0000) Subject: Clean up SENFScons.py X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=62464586315edf52fbcc613acb4a8a7e919fd8e2;p=senf.git Clean up SENFScons.py Rename macro prefix SATLIB to SENF Begin socket library documentation git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@174 270642c3-0616-0410-b53a-bc976706d245 --- diff --git a/Socket/FhHierarchy.dia b/Socket/FhHierarchy.dia new file mode 100644 index 0000000..763745f Binary files /dev/null and b/Socket/FhHierarchy.dia differ diff --git a/Socket/Mainpage.dox b/Socket/Mainpage.dox index 09e881b..15993a6 100644 --- a/Socket/Mainpage.dox +++ b/Socket/Mainpage.dox @@ -33,12 +33,43 @@ socket representation. This frees you of having to manage the socket lifetime explicitly. + \section socket_hierarchy The FileHandle hierarchy + + \image html FhHierarchy.png + + The senf::FileHandle class is the base of a hierarchy of socket + handle classes (realized as templates). These classes provide an + interface to the complete socket API. While going down the + inheritance hierarchy, the interface will be more and more + complete. + + The most complete interface is provided by + senf::ProtocolClientSocketHandle and + senf::ProtocolServerSocketHandle. The template Arguments specifies + the Protocol class of the underlying socket type. These are the + \e only classes having public constructors and are therefore the + only classes, which may be created by the library user. You will + normally use these classes by naming a specific socket typedef + (e.g. senf::TCPv4ClientSocketHandle). + + However, to aid writing flexible and generic code, the socket + library provides the senf::ClientSocketHandle and + senf::ServerSocketHandle class templates. These templates + implement a family of closely related classes based on the + specification of the socket policy. This policy specification may + be \e incomplete (see below). Instances of + senf::ClientSocketHandle/senf::ServerSocketHandle can be assigned + and converted to different ClientSocketHandle/ServerSocketHandle + types as long as the policy specifications are compatible. + \attention It is very important, to (almost) always pass the socket handle by value. The socket handle is a very lightweight class and designed to be used like an ordinary built-in type. This is very important in combination with the policy interface. \section policy_framework The policy framework + + \image html SocketPolicy.png The policy framework conceptually implements a list of parallel inheritance hierarchies each covering a specific interface aspect @@ -70,6 +101,42 @@
configures, if and how buffering is configured for a socket
+ Every Policy value is identified by a class type. The policy types + themselves built an inheritance hierarchy for each policy + axis. For each policy axis, the root of this tree is the class + named '(axis name)Base' (e.g. \p FramingPolicyBase or \p + CommunicationPolicyBase) which is aliased to 'Unspecified(axis + name)' (e.g. \p UnspecifiedFramingPolicy or \p + UnspecifiedCommunicationPolicy). + + The senf::SocketPolicy template combines a set of policy classes, + one for each policy axis. Together, they define the behavior of a + socket handle. The socket handle instances do net implement any + socket functionality themselves, instead defering the + implementation to the socket classes. The interface is therefore + \e not implemented using virtual members, all important socket + functions can be inlined by the compiler to create highly + efficient code. + + Two SocketPolicy instances are considered compatible, if all + policy axis are compatible. A policy axis is compatible, if one + policy class is either the same as the other or derived from + it. Two SocketHandle instances can be converted into each other, + as long as the SocketPolicies are compatible. + + \section policy_interface The policy interface + + The socket handle classes and templates only implement the most + important socket API methods. To access the complete API, the + protocol interface is provided. Access to the protocol interface + is only possible via senf::ProtocolClientSocketHandle and + senf::ProtocolServerSocketHandle which have the necessary \c + protocol() member. This member returns a reference to the protocol + class instance which contains members covering all the API + function snot found in the SocketHandle interface. The protocol + interface is specific to the protocol. It's implementation is + quite free. Every protocol class will define the complete and + specific socket policy of it's socket handle. */ /** \page extend Extending the Library @@ -77,10 +144,9 @@ /** \page implementation Implementation notes - \image html "../../SocketLibrary-classes.png" Class hierarchy + \image html SocketLibrary-classes.png */ - // Local Variables: // mode: c++ diff --git a/Socket/SConscript b/Socket/SConscript index ffd61cd..9aff674 100644 --- a/Socket/SConscript +++ b/Socket/SConscript @@ -16,4 +16,6 @@ SENFSCons.Lib(env, SENFSCons.Doxygen(env, extra_sources = [ env.Dia2Png('SocketLibrary-classes.dia'), + env.Dia2Png('FhHierarchy.dia'), + env.Dia2Png('SocketPolicy.dia'), ]) diff --git a/Socket/SocketLibrary-classes.dia b/Socket/SocketLibrary-classes.dia index c0e9d1f..f31dd1d 100644 Binary files a/Socket/SocketLibrary-classes.dia and b/Socket/SocketLibrary-classes.dia differ diff --git a/Socket/SocketPolicy.ct b/Socket/SocketPolicy.ct index cc21916..cbcfd30 100644 --- a/Socket/SocketPolicy.ct +++ b/Socket/SocketPolicy.ct @@ -32,12 +32,12 @@ #define SP_TemplateArgs(x1,x2,n,SomePolicy) BOOST_PP_COMMA_IF(n) class BOOST_PP_CAT(SomePolicy,_) #define SP_TemplateParams(x1,x2,n,SomePolicy) BOOST_PP_COMMA_IF(n) BOOST_PP_CAT(SomePolicy,_) -template < BOOST_PP_SEQ_FOR_EACH_I( SP_TemplateArgs, , SATLIB_SOCKET_POLICIES ) > -prefix_ void senf::SocketPolicy< BOOST_PP_SEQ_FOR_EACH_I( SP_TemplateParams, , SATLIB_SOCKET_POLICIES ) >:: +template < BOOST_PP_SEQ_FOR_EACH_I( SP_TemplateArgs, , SENF_SOCKET_POLICIES ) > +prefix_ void senf::SocketPolicy< BOOST_PP_SEQ_FOR_EACH_I( SP_TemplateParams, , SENF_SOCKET_POLICIES ) >:: checkBaseOf(SocketPolicyBase const & other) { # define SP_CheckPolicy(x1,x2,SomePolicy) (void) dynamic_cast(other.BOOST_PP_CAT(the,SomePolicy)()); - BOOST_PP_SEQ_FOR_EACH( SP_CheckPolicy, , SATLIB_SOCKET_POLICIES ) + BOOST_PP_SEQ_FOR_EACH( SP_CheckPolicy, , SENF_SOCKET_POLICIES ) # undef SP_CheckPolicy } diff --git a/Socket/SocketPolicy.dia b/Socket/SocketPolicy.dia new file mode 100644 index 0000000..56ff6e8 Binary files /dev/null and b/Socket/SocketPolicy.dia differ diff --git a/Socket/SocketPolicy.hh b/Socket/SocketPolicy.hh index e821d92..91ee1bf 100644 --- a/Socket/SocketPolicy.hh +++ b/Socket/SocketPolicy.hh @@ -36,7 +36,7 @@ namespace senf { // be adjusted accordingly). However, AddressingPolicy MUST always // be the first Policy member ... -# define SATLIB_SOCKET_POLICIES \ +# define SENF_SOCKET_POLICIES \ (AddressingPolicy) \ (FramingPolicy) \ (CommunicationPolicy) \ diff --git a/Socket/SocketPolicy.ih b/Socket/SocketPolicy.ih index a6d9ebb..dabdf26 100644 --- a/Socket/SocketPolicy.ih +++ b/Socket/SocketPolicy.ih @@ -53,7 +53,7 @@ namespace senf { -# define SATLIB_SOCKET_POLICIES_N BOOST_PP_SEQ_SIZE( SATLIB_SOCKET_POLICIES ) +# define SENF_SOCKET_POLICIES_N BOOST_PP_SEQ_SIZE( SENF_SOCKET_POLICIES ) // This REALLY is bad ... but we just need an Address member in // AddressingPolicyBase as long as ClientSocketHandle / @@ -72,7 +72,7 @@ namespace senf { { virtual ~ BOOST_PP_CAT(SomePolicy,Base) () {} }; \ typedef BOOST_PP_CAT(SomePolicy,Base) BOOST_PP_CAT(Unspecified,SomePolicy); - BOOST_PP_SEQ_FOR_EACH( SP_DeclareBase, , BOOST_PP_SEQ_POP_FRONT( SATLIB_SOCKET_POLICIES ) ) + BOOST_PP_SEQ_FOR_EACH( SP_DeclareBase, , BOOST_PP_SEQ_POP_FRONT( SENF_SOCKET_POLICIES ) ) # undef SP_DeclareBase @@ -86,7 +86,7 @@ namespace senf { virtual BOOST_PP_CAT(SomePolicy,Base) const & BOOST_PP_CAT(the,SomePolicy) () const \ { return BOOST_PP_CAT(BOOST_PP_CAT(the,SomePolicy),_); } - BOOST_PP_SEQ_FOR_EACH( SP_DeclareTypedef, , SATLIB_SOCKET_POLICIES ) + BOOST_PP_SEQ_FOR_EACH( SP_DeclareTypedef, , SENF_SOCKET_POLICIES ) # undef SP_DeclareTypedef }; @@ -95,7 +95,7 @@ namespace senf { BOOST_PP_COMMA_IF( n ) \ class BOOST_PP_CAT(SomePolicy,_) = BOOST_PP_CAT(SomePolicy,Base) - template < BOOST_PP_SEQ_FOR_EACH_I( SP_TemplateArgs, , SATLIB_SOCKET_POLICIES ) > + template < BOOST_PP_SEQ_FOR_EACH_I( SP_TemplateArgs, , SENF_SOCKET_POLICIES ) > struct SocketPolicy : public SocketPolicyBase { @@ -105,7 +105,7 @@ namespace senf { BOOST_PP_CAT(SomePolicy,Base) const & BOOST_PP_CAT(the,SomePolicy) () const \ { return BOOST_PP_CAT(BOOST_PP_CAT(the,SomePolicy),_); } - BOOST_PP_SEQ_FOR_EACH( SP_DeclarePolicyMember, , SATLIB_SOCKET_POLICIES ) + BOOST_PP_SEQ_FOR_EACH( SP_DeclarePolicyMember, , SENF_SOCKET_POLICIES ) # undef SP_DeclarePolicyMember static void checkBaseOf(SocketPolicyBase const & other); @@ -129,15 +129,15 @@ namespace impl { BOOST_PP_COMMA_IF( m ) \ BOOST_PP_IIF( BOOST_PP_EQUAL(n,m), Policy, typename Base::SomePolicy ) -# define BOOST_PP_LOCAL_LIMITS (0, BOOST_PP_DEC( SATLIB_SOCKET_POLICIES_N ) ) +# define BOOST_PP_LOCAL_LIMITS (0, BOOST_PP_DEC( SENF_SOCKET_POLICIES_N ) ) # define BOOST_PP_LOCAL_MACRO(n) \ - SocketPolicy_rv MakeSocketPolicy_merge_(BOOST_PP_CAT( BOOST_PP_SEQ_ELEM( n, SATLIB_SOCKET_POLICIES ),Base)*); \ + SocketPolicy_rv MakeSocketPolicy_merge_(BOOST_PP_CAT( BOOST_PP_SEQ_ELEM( n, SENF_SOCKET_POLICIES ),Base)*); \ \ template \ struct MakeSocketPolicy_merge)> \ { \ typedef SocketPolicy< \ - BOOST_PP_SEQ_FOR_EACH_I( SP_DeclareMakeSocketPolicy_merge_member, n, SATLIB_SOCKET_POLICIES ) \ + BOOST_PP_SEQ_FOR_EACH_I( SP_DeclareMakeSocketPolicy_merge_member, n, SENF_SOCKET_POLICIES ) \ > type; \ }; @@ -173,13 +173,13 @@ namespace impl { template SocketPolicy_rv<1> SocketPolicy_checkcompat_( - BOOST_PP_SEQ_FOR_EACH_I( SP_DeclareArguments, , SATLIB_SOCKET_POLICIES ) ); + BOOST_PP_SEQ_FOR_EACH_I( SP_DeclareArguments, , SENF_SOCKET_POLICIES ) ); # undef SP_DeclareArguments template SocketPolicy_rv<2> SocketPolicy_checkcompat_( - BOOST_PP_ENUM_PARAMS( SATLIB_SOCKET_POLICIES_N, void * BOOST_PP_INTERCEPT ) ); + BOOST_PP_ENUM_PARAMS( SENF_SOCKET_POLICIES_N, void * BOOST_PP_INTERCEPT ) ); template struct SocketPolicy_checkcompat @@ -200,17 +200,17 @@ namespace impl { struct SocketPolicy_compatibility : public SocketPolicy_checkcompat< sizeof( SocketPolicy_checkcompat_( - BOOST_PP_SEQ_FOR_EACH_I( SP_DeclareArguments, , SATLIB_SOCKET_POLICIES ) )) > + BOOST_PP_SEQ_FOR_EACH_I( SP_DeclareArguments, , SENF_SOCKET_POLICIES ) )) > {}; } // namespace impl - template < BOOST_PP_ENUM_PARAMS_WITH_A_DEFAULT( SATLIB_SOCKET_POLICIES_N, class T, senf::impl::nil ) > + template < BOOST_PP_ENUM_PARAMS_WITH_A_DEFAULT( SENF_SOCKET_POLICIES_N, class T, senf::impl::nil ) > class MakeSocketPolicy : public boost::mpl::if_< boost::is_convertible< T0*, SocketPolicyBase* >, - impl::MakeSocketPolicy_impl< T0, boost::mpl::vector< BOOST_PP_ENUM_SHIFTED_PARAMS( SATLIB_SOCKET_POLICIES_N, T ) > >, + impl::MakeSocketPolicy_impl< T0, boost::mpl::vector< BOOST_PP_ENUM_SHIFTED_PARAMS( SENF_SOCKET_POLICIES_N, T ) > >, impl::MakeSocketPolicy_impl< SocketPolicy<>, - boost::mpl::vector< BOOST_PP_ENUM_PARAMS( SATLIB_SOCKET_POLICIES_N, T ) > > >::type + boost::mpl::vector< BOOST_PP_ENUM_PARAMS( SENF_SOCKET_POLICIES_N, T ) > > >::type {}; template @@ -237,7 +237,7 @@ namespace impl { : public boost::enable_if_c< ! BOOST_PP_CAT(SomePolicy,Is)::value > \ {}; - BOOST_PP_SEQ_FOR_EACH( SP_DefineConditions, , SATLIB_SOCKET_POLICIES ) + BOOST_PP_SEQ_FOR_EACH( SP_DefineConditions, , SENF_SOCKET_POLICIES ) # undef SP_DefineConditions diff --git a/doclib/Doxyfile.global b/doclib/Doxyfile.global index 22a55f8..27bccac 100644 --- a/doclib/Doxyfile.global +++ b/doclib/Doxyfile.global @@ -87,7 +87,7 @@ EXCLUDE_PATTERNS = *.test.cc .* EXAMPLE_PATH = EXAMPLE_PATTERNS = * EXAMPLE_RECURSIVE = NO -IMAGE_PATH = +IMAGE_PATH = . INPUT_FILTER = FILTER_PATTERNS = FILTER_SOURCE_FILES = NO diff --git a/senfscons/SENFSCons.py b/senfscons/SENFSCons.py index bed67e0..7308c0e 100644 --- a/senfscons/SENFSCons.py +++ b/senfscons/SENFSCons.py @@ -113,8 +113,7 @@ def GlobSources(exclude=[]): def StandardTargets(env): all = env.Alias('all') - env.Clean(all, [ '.sconsign', '.sconf_temp', 'config.log', 'ChangeLog.bak', '.clean' - ] + glob.glob("*~")) + env.Clean(all, [ '.sconsign', '.sconf_temp', 'config.log' ]) env.Depends(all, '.') def GlobalTargets(env): @@ -151,14 +150,7 @@ def Objects(env, sources, testSources = None, LIBS = []): return objects -def DoxyGlob(exclude=[]): - sources = [ f - for ext in ("cci", "ct", "cti", "h", "hh", "ih", "mmc", "dox") - for f in glob.glob("*."+ext) - if f not in exclude ] - return sources - -def Doxygen(env, doxyfile="Doxyfile", extra_sources = []): +def Doxygen(env, doxyfile = "Doxyfile", extra_sources = []): docs = env.Doxygen(doxyfile) # The last target is the (optional) tagfile if os.path.basename(str(docs[-1])) != '.stamp':