[Opentnl-cvs] tnl/tnl tnlMethodDispatch.h,1.11,1.12 tnlNetEvent.h,1.1,1.2 tnlRPC.h,1.13,1.14

[Mark F. <mar...@us...>]

Update of /cvsroot/opentnl/tnl/tnl
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv5310/tnl

Modified Files:
	tnlMethodDispatch.h tnlNetEvent.h tnlRPC.h 
Log Message:
Added updated documentation for the new RPC functionality
Updated NetEvent documentation
Upped version number

Index: tnlRPC.h
===================================================================
RCS file: /cvsroot/opentnl/tnl/tnl/tnlRPC.h,v
retrieving revision 1.13
retrieving revision 1.14
diff -C2 -d -r1.13 -r1.14
*** tnlRPC.h	22 Feb 2005 05:55:45 -0000	1.13
--- tnlRPC.h	22 Feb 2005 18:04:53 -0000	1.14
***************
*** 52,62 ****
  {
  public:
!    TNL_DECLARE_RPC(rpcPrintHelloWorld, ());
  };
  
! TNL_IMPLEMENT_RPC(SimpleEventConnection, rpcPrintHelloWorld, (),
     NetClassGroupGameMask, RPCGuaranteedOrdered, RPCDirAny, 0)
  {
!    printf("Hello, World!");
  }
   
--- 52,64 ----
  {
  public:
!    TNL_DECLARE_RPC(rpcPrintString, (StringPtr theString, U32 messageCount));
  };
  
! TNL_IMPLEMENT_RPC(SimpleEventConnection, rpcPrintString, 
!    (StringPtr theString, messageCount), (theString, messageCount),
     NetClassGroupGameMask, RPCGuaranteedOrdered, RPCDirAny, 0)
  {
!    for(U32 i = 0; i < messageCount; i++)
!       printf("%s", theString.getString());
  }
   
***************
*** 64,85 ****
  void somefunction(SimpleEventConnection *connection)
  {
!    connection->rpcPrintHelloWorld();
  }
  @endcode
  
  In this example the class SimpleEventConnection is declared to have
! a single RPC method named rpcPrintHelloWorld.  The TNL_DECLARE_RPC macro
  can just be viewed as a different way of declaring a class's member functions,
  with the name as the first argument and the parenthesized parameter list
  as the second.  Since RPC calls execute on a remote host, they never have
! a return value - athough a second RPC could be declared to pass messages
  in the other direction.
  
  The body of the RPC method is declared using the TNL_IMPLEMENT_RPC macro,
! which has some additional arguments, including which NetClassMask the RPC is valid
! in, what level of data guarantee it uses, the direction it is allowed to be called
! in the connection and a version number.  The body of the function, which
! in this case prints the message "Hello, World!" to stdout, is executed on
! the remote host from which the method was originally invoked.
  
  As the somefunction code demonstrates, RPC's are invoked in the same way
--- 66,87 ----
  void somefunction(SimpleEventConnection *connection)
  {
!    connection->rpcPrintString("Hello World!", 5);
  }
  @endcode
  
  In this example the class SimpleEventConnection is declared to have
! a single RPC method named rpcPrintString.  The TNL_DECLARE_RPC macro
  can just be viewed as a different way of declaring a class's member functions,
  with the name as the first argument and the parenthesized parameter list
  as the second.  Since RPC calls execute on a remote host, they never have
! a return value - although a second RPC could be declared to pass messages
  in the other direction.
  
  The body of the RPC method is declared using the TNL_IMPLEMENT_RPC macro,
! which has some additional arguments: the named parameter list without the types,
! which NetClassMask the RPC is valid in, what level of data guarantee it uses, 
! the direction it is allowed to be called on the connection and a version number.  
! The body of the function, which in this case prints the passed message "Hello, World!" 5 times
! to stdout, is executed on the remote host from which the method was originally invoked.
  
  As the somefunction code demonstrates, RPC's are invoked in the same way
***************
*** 93,97 ****
  the body of the new RPC.
  
! RPC methods can take the following types as arguments:
   - S8, U8
   - S16, U16
--- 95,102 ----
  the body of the new RPC.
  
! Internally the RPC macros construct new NetEvent classes and encapsulate the
! function call arguments using the FunctorDecl template classes.  By default
! the following types are allowed as parameters to RPC methods:
! 
   - S8, U8
   - S16, U16
***************
*** 104,112 ****
   - RangedU32<>
   - bool
!  - const char *
   - StringTableEntry
!  - ByteBufferRef
!  - IPAddressRef
!  - Vector<> of all the preceding types except ByteBufferRef and IPAddressRef
  
  The Int, SignedInt, Float, SignedFloat and RangedU32 template types use the
--- 109,121 ----
   - RangedU32<>
   - bool
!  - StringPtr
   - StringTableEntry
!  - ByteBufferPtr
!  - IPAddress
!  - Vector<> of all the preceding types
! 
! New types can be supported by implementing a template override for the
! Types::read and Types::write functions.  All arguments to RPCs must be
! passed by value (ie no reference or pointer types).
  
  The Int, SignedInt, Float, SignedFloat and RangedU32 template types use the

Index: tnlNetEvent.h
===================================================================
RCS file: /cvsroot/opentnl/tnl/tnl/tnlNetEvent.h,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** tnlNetEvent.h	20 Apr 2004 04:27:18 -0000	1.1
--- tnlNetEvent.h	22 Feb 2005 18:04:53 -0000	1.2
***************
*** 61,65 ****
  ///        chat messages or file transfers.
  ///
! /// There are 6 methods that you need to implement if you want to make a
  /// basic NetEvent subclass, and 2 macros you need to call.
  ///
--- 61,65 ----
  ///        chat messages or file transfers.
  ///
! /// There are 3 methods that you need to implement if you want to make a
  /// basic NetEvent subclass, and 2 macros you need to call.
  ///
***************
*** 74,80 ****
  ///    ~SimpleMessageEvent();
  ///
! ///    virtual void pack   (NetConnection *conn, BitStream *bstream);
! ///    virtual void unpack (NetConnection *conn, BitStream *bstream);
! ///    virtual void process(NetConnection *conn);
  ///
  ///    TNL_DECLARE_CLASS(SimpleMessageEvent);
--- 74,80 ----
  ///    ~SimpleMessageEvent();
  ///
! ///    virtual void pack   (EventConnection *conn, BitStream *bstream)
! ///    virtual void unpack (EventConnection *conn, BitStream *bstream);
! ///    virtual void process(EventConnection *conn);
  ///
  ///    TNL_DECLARE_CLASS(SimpleMessageEvent);
***************
*** 84,90 ****
  /// @endcode
  ///
! /// Notice the two macros which we call. The first, TNL_DECLARE_CLASS() is there
! /// to register the static class functions and NetClassRep object that will assign
! /// this class a network ID and allow instances to be construced by ID.
  ///
  /// The second, TNL_IMPLEMENT_NETEVENT(), instantiates the NetClassRep and
--- 84,89 ----
  /// @endcode
  ///
! /// The first macro called, TNL_DECLARE_CLASS() registers the static class functions and NetClassRep object that will assign
! /// this class a network ID and allow instances to be constructed by ID.
  ///
  /// The second, TNL_IMPLEMENT_NETEVENT(), instantiates the NetClassRep and
***************
*** 94,100 ****
  /// older clients to be updated.
  ///
! /// In the constructor for the event, you must also specify, by way of the constructor
! /// for the base NetEvent class, what guarantee type the event has, and in which direction(s)
! /// it is allowed to travel over the connection.  The guarantee type can be one of:
  ///      - <b>NetEvent::GuaranteedOrdered</b>, for guaranteed, ordered events
  ///      - <b>NetEvent::Guaranteed</b>, for guaranteed events
--- 93,99 ----
  /// older clients to be updated.
  ///
! /// In the constructor for the event the guarantee type of the event and the direction it will be
! /// allowed to travel over the connection, must be specified by way of the constructor
! /// for the base NetEvent class.  The guarantee type can be one of:
  ///      - <b>NetEvent::GuaranteedOrdered</b>, for guaranteed, ordered events
  ///      - <b>NetEvent::Guaranteed</b>, for guaranteed events
***************
*** 102,108 ****
  ///
  /// It is also a good idea to clearly specify which direction the event is allowed to travel.
! /// If your game has a certain set of message events that are only sent from server to client,
! /// then the network system can do some error checking for you, in order to prevent hacks that may
! /// otherwise crash or compromise your game.  The valid event directions are:
  ///      - <b>NetEvent::DirAny</b>, this event can be sent from server to client
  ///        or from client to server
--- 101,107 ----
  ///
  /// It is also a good idea to clearly specify which direction the event is allowed to travel.
! /// If the program has a certain set of message events that are only sent from server to client,
! /// then the network system can enforce that error checking automatically, in order to prevent hacks that may
! /// otherwise crash or compromise the program.  The valid event directions are:
  ///      - <b>NetEvent::DirAny</b>, this event can be sent from server to client
  ///        or from client to server
***************
*** 115,126 ****
  ///
  /// @note TNL allows you to call NetConnection::setLastError() on the EventConnection passed to
! ///       your NetEvent. You can cause the connection to abort if invalid data is received, specifying
  ///       a reason to the user.
  ///
! /// Now, the 5 methods which we have above; the constructor and destructor need only do
! /// whatever book-keeping is needed for your specific implementation, in addition to calling
! /// the NetEvent constructor with the direction and type information the networking system
! /// needs to function. In our case, we just need to allocate/deallocate the space for our string,
! /// and specify the event as guaranteed ordered and bidirectional.
  ///
  /// @code
--- 114,125 ----
  ///
  /// @note TNL allows you to call NetConnection::setLastError() on the EventConnection passed to
! ///       the NetEvent. This will cause the connection to abort if invalid data is received, specifying
  ///       a reason to the user.
  ///
! /// Of the 5 methods declared above; the constructor and destructor need only do
! /// whatever book-keeping is needed for the specific implementation, in addition to calling
! /// the NetEvent constructor with the direction and type information that the networking system
! /// needs to function. In this case, the SimpleMessageEvent simply allocates/deallocates the space for the string,
! /// and specifies the event as guaranteed ordered and bidirectional.
  ///
  /// @code
***************
*** 141,145 ****
  /// @endcode
  ///
! /// Simple as that! Now, onto pack(), unpack(), process().
  ///
  /// <b>pack()</b> is responsible for packing the event over the wire:
--- 140,144 ----
  /// @endcode
  ///
! /// The 3 other functions that must be overridden for evern NetEvent are pack(), unpack() and process().
  ///
  /// <b>pack()</b> is responsible for packing the event over the wire:
***************
*** 181,186 ****
  /// @endcode
  ///
! /// The NetEvent is sent over the wire in a straightforward way (assuming you have a
! /// handle to an EventConnection):
  ///
  /// @code
--- 180,184 ----
  /// @endcode
  ///
! /// Posting an event to the remote host on a connection is simple:
  ///
  /// @code
***************
*** 192,196 ****
  /// Finally, for more advanced applications, notifyPosted() is called when the event is posted
  /// into the send queue, notifySent() is called whenever the event is
! /// sent over the wire, in NetConnection::eventWritePacket(). notifyDelivered() is called
  /// when the packet is finally received or (in the case of Unguaranteed packets) dropped.
  ///
--- 190,194 ----
  /// Finally, for more advanced applications, notifyPosted() is called when the event is posted
  /// into the send queue, notifySent() is called whenever the event is
! /// sent over the wire, in EventConnection::eventWritePacket(). notifyDelivered() is called
  /// when the packet is finally received or (in the case of Unguaranteed packets) dropped.
  ///

Index: tnlMethodDispatch.h
===================================================================
RCS file: /cvsroot/opentnl/tnl/tnl/tnlMethodDispatch.h,v
retrieving revision 1.11
retrieving revision 1.12
diff -C2 -d -r1.11 -r1.12
*** tnlMethodDispatch.h	22 Feb 2005 05:55:45 -0000	1.11
--- tnlMethodDispatch.h	22 Feb 2005 18:04:52 -0000	1.12
***************
*** 55,81 ****
--- 55,95 ----
     };
  
+    /// Reads a string from a BitStream.
     extern void read(TNL::BitStream &s, TNL::StringPtr *val);
+    /// Rrites a string into a BitStream.
     extern void write(TNL::BitStream &s, TNL::StringPtr &val);
+    /// Reads a ByteBuffer from a BitStream.
     extern void read(TNL::BitStream &s, TNL::ByteBufferPtr *val);
+    /// Writes a ByteBuffer into a BitStream.
     extern void write(TNL::BitStream &s, TNL::ByteBufferPtr &val);
+    /// Reads an IP address from a BitStream.
     extern void read(TNL::BitStream &s, TNL::IPAddress *val);
+    /// Writes an IP address into a BitStream.
     extern void write(TNL::BitStream &s, TNL::IPAddress &val);
  
+    /// Reads a StringTableEntry from a BitStream.
     inline void read(TNL::BitStream &s, TNL::StringTableEntry *val)
     {
        s.readStringTableEntry(val);
     }
+    /// Writes a StringTableEntry into a BitStream.
     inline void write(TNL::BitStream &s, TNL::StringTableEntry &val)
     {
        s.writeStringTableEntry(val);
     }
+ 
+    /// Reads a generic object from a BitStream.  This can be used for any
+    /// type supported by BitStream::read.
     template <typename T> inline void read(TNL::BitStream &s, T *val)
     { 
        s.read(val);
     }
+    /// Writes a generic object into a BitStream.  This can be used for any
+    /// type supported by BitStream::write.
     template <typename T> inline void write(TNL::BitStream &s, T &val)
     { 
        s.write(val);
     }
+    /// Reads a Vector of objects from a BitStream.
     template <typename T> inline void read(TNL::BitStream &s, TNL::Vector<T> *val)
     {
***************
*** 85,88 ****
--- 99,103 ----
           read(s, &((*val)[i]));
     }
+    /// Writes a Vector of objects into a BitStream.
     template <typename T> void write(TNL::BitStream &s, TNL::Vector<T> &val)
     {
***************
*** 91,99 ****
           write(s, val[i]);
     }
! 
     template <TNL::U32 BitCount> inline void read(TNL::BitStream &s, TNL::Int<BitCount> *val)
     {
        val->value = s.readInt(BitCount);
     }
     template <TNL::U32 BitCount> inline void write(TNL::BitStream &s,TNL::Int<BitCount> &val)
     {
--- 106,115 ----
           write(s, val[i]);
     }
!    /// Reads a bit-compressed integer from a BitStream.
     template <TNL::U32 BitCount> inline void read(TNL::BitStream &s, TNL::Int<BitCount> *val)
     {
        val->value = s.readInt(BitCount);
     }
+    /// Writes a bit-compressed integer into a BitStream.
     template <TNL::U32 BitCount> inline void write(TNL::BitStream &s,TNL::Int<BitCount> &val)
     {
***************
*** 101,108 ****
--- 117,126 ----
     }
  
+    /// Reads a bit-compressed signed integer from a BitStream.
     template <TNL::U32 BitCount> inline void read(TNL::BitStream &s, TNL::SignedInt<BitCount> *val)
     {
        val->value = s.readSignedInt(BitCount);
     }
+    /// Writes a bit-compressed signed integer into a BitStream.
     template <TNL::U32 BitCount> inline void write(TNL::BitStream &s,TNL::SignedInt<BitCount> &val)
     {
***************
*** 110,137 ****
     }
  
!    template <TNL::U32 T, TNL::U32 U> inline void read(TNL::BitStream &s, TNL::RangedU32<T,U> *val)
     {
!       val->value = s.readRangedU32(T, U);
     }
!    template <TNL::U32 T, TNL::U32 U> inline void write(TNL::BitStream &s,TNL::RangedU32<T,U> &val)
     {
!       s.writeRangedU32(val.value, T, U);
     }
  
!    template <TNL::U32 T> inline void read(TNL::BitStream &s, TNL::Float<T> *val)
     {
!       val->value = s.readFloat(T);
     }
!    template <TNL::U32 T> inline void write(TNL::BitStream &s,TNL::Float<T> &val)
     {
!       s.writeFloat(val.value, T);
     }
!    template <TNL::U32 T> inline void read(TNL::BitStream &s, TNL::SignedFloat<T> *val)
     {
!       val->value = s.readSignedFloat(T);
     }
!    template <TNL::U32 T> inline void write(TNL::BitStream &s,TNL::SignedFloat<T> &val)
     {
!       s.writeSignedFloat(val.value, T);
     }
  };
--- 128,162 ----
     }
  
!    /// Reads a bit-compressed RangedU32 from a BitStream.
!    template <TNL::U32 MinValue, TNL::U32 MaxValue> inline void read(TNL::BitStream &s, TNL::RangedU32<MinValue,MaxValue> *val)
     {
!       val->value = s.readRangedU32(MinValue, MaxValue);
     }
! 
!    /// Writes a bit-compressed RangedU32 into a BitStream.
!    template <TNL::U32 MinValue, TNL::U32 MaxValue> inline void write(TNL::BitStream &s,TNL::RangedU32<MinValue,MaxValue> &val)
     {
!       s.writeRangedU32(val.value, MinValue, MaxValue);
     }
  
!    /// Reads a bit-compressed SignedFloat (-1 to 1) from a BitStream.
!    template <TNL::U32 BitCount> inline void read(TNL::BitStream &s, TNL::Float<BitCount> *val)
     {
!       val->value = s.readFloat(BitCount);
     }
!    /// Writes a bit-compressed SignedFloat (-1 to 1) into a BitStream.
!    template <TNL::U32 BitCount> inline void write(TNL::BitStream &s,TNL::Float<BitCount> &val)
     {
!       s.writeFloat(val.value, BitCount);
     }
!    /// Reads a bit-compressed Float (0 to 1) from a BitStream.
!    template <TNL::U32 BitCount> inline void read(TNL::BitStream &s, TNL::SignedFloat<BitCount> *val)
     {
!       val->value = s.readSignedFloat(BitCount);
     }
!    /// Writes a bit-compressed Float (0 to 1) into a BitStream.
!    template <TNL::U32 BitCount> inline void write(TNL::BitStream &s,TNL::SignedFloat<BitCount> &val)
     {
!       s.writeSignedFloat(val.value, BitCount);
     }
  };
***************
*** 139,149 ****
--- 164,190 ----
  namespace TNL {
  
+ /// Base class for FunctorDecl template classes.  The Functor objects
+ /// store the parameters and member function pointer for the invocation
+ /// of some class member function.  Functor is used in TNL by the
+ /// RPC mechanism, the journaling system and the ThreadQueue to store
+ /// a function for later transmission and dispatch, either to a remote
+ /// host, a journal file, or another thread in the process.
  struct Functor {
+    /// Construct the Functor.
     Functor() {}
+    /// Destruct the Functor.
     virtual ~Functor() {}
+    /// Reads this Functor from a BitStream.
     virtual void read(BitStream &stream) = 0;
+    /// Writes this Functor to a BitStream.
     virtual void write(BitStream &stream) = 0;
+    /// Dispatch the function represented by the Functor.
     virtual void dispatch(void *t) = 0;
  };
+ 
+ /// FunctorDecl template class.  This class is specialized based on the
+ /// member function call signature of the method it represents.  Other
+ /// specializations hold specific member function pointers and slots
+ /// for each of the function arguments.
  template <class T> 
  struct FunctorDecl : public Functor {