[Opentnl-cvs] tnl/tnl tnlMethodDispatch.h,1.11,1.12 tnlNetEvent.h,1.1,1.2 tnlRPC.h,1.13,1.14
Brought to you by:
mark_frohnmayer,
s_alanet
From: Mark F. <mar...@us...> - 2005-02-22 18:05:05
|
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 { |