X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Socket%2FMainpage.dox;h=2721d3696778685f2e6d12b66b802baf87efeabb;hb=032707d24b1059febe83ce56b11fd79df106c6e2;hp=09e881bbea18ad8530fd406326218bc91e07191e;hpb=cd9dd31c21fb021fe2c27ff52419b0e93340a964;p=senf.git diff --git a/Socket/Mainpage.dox b/Socket/Mainpage.dox index 09e881b..2721d36 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,17 +101,153 @@
+ typedef senf::ProtocolClientSocketHandle MyProtocolClientSocketHandle;
+ typedef senf::ProtocolServerSocketHandle MyProtocolServerSocketHandle;
+
+
+ \section extend_policy Extending the policy framework
+
+ If you have to extend the policy framework, you will need to be
+ aware of some important limitations of the socket library:
+
+ \li When you define a new policy for some axis, this new policy
+ must not be derived from one of the existing concrete
+ policy classes (except of course the respective policy axis
+ base class). This is important since the policy type is \e not
+ polymorphic. The policy to be used is selected by the compiler
+ using the \e static type, which is exactly what is desired,
+ since this allows calls to be efficiently inlined.
+
+ \li Therefore, extending the policy framework will make the new
+ socket probably \e incompatible with generic code which relies
+ on the policy axis which is extended. Example: If you write a
+ new write policy because your protocol does not use ordinary
+ write() system calls but some protocol specific API, Then any
+ generic function relying on senf::WritablePolicy will \e not
+ work with the new socket, since the socket does \e not have
+ this policy, it has some other kind of write policy.
+
+ Therefore you need to be careful of what you are doing. The first
+ step is to find out, which policy you will have to implement. For
+ this, find the senf::ClientSocketHandle and/or
+ senf::ServerSocketHandle members you want to change. The following
+ table shows, which policy axis is responsible for which
+ members. The policy axis base class documentation contains further
+ information on how to implement that policy.
+
+ SocketHandle member | Policy member |
---|---|
senf::ClientSocketHandle::read | ReadPolicy::read (\ref senf::ReadPolicyBase) |
senf::ClientSocketHandle::readfrom | ReadPolicy::readfrom (\ref senf::ReadPolicyBase) |
senf::ClientSocketHandle::write | WritePolicy::write (\ref senf::WritePolicyBase) |
senf::ClientSocketHandle::writeto | WritePolicy::writeto (\ref senf::WritePolicyBase) |
senf::ClientSocketHandle::connect | AddressingPolicy::connect (\ref senf::AddressingPolicyBase) |
senf::ClientSocketHandle::bind | AddressingPolicy::bind (\ref senf::AddressingPolicyBase) |
senf::ClientSocketHandle::peer | AddressingPolicy::peer (\ref senf::AddressingPolicyBase) |
senf::ClientSocketHandle::local | AddressingPolicy::local (\ref senf::AddressingPolicyBase) |
senf::ClientSocketHandle::rcvbuf | BufferingPolicy::sndbuf (\ref senf::BufferingPolicyBase) |
senf::ClientSocketHandle::sndbuf | BufferingPolicy::rcvbuf (\ref senf::BufferingPolicyBase) |
senf::ServerSocketHandle::bind | AddressingPolicy::bind (\ref senf::AddressingPolicyBase) |
senf::ServerSocketHandle::listen | CommunicationPolicy::listen (\ref senf::CommunicationPolicyBase) |
senf::ServerSocketHandle::local | AddressingPolicy::local (\ref senf::AddressingPolicyBase) |
senf::ServerSocketHandle::accept | CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase) |
senf::ServerSocketHandle::acceptfrom | CommunicationPolicy::accept (\ref senf::CommunicationPolicyBase) |