--- a/doc/doxygen/doxygen.cfg Mon Dec 08 12:46:37 2008 +0000
+++ b/doc/doxygen/doxygen.cfg Mon Dec 08 15:02:05 2008 +0000
@@ -1,6 +1,17 @@
+# general
PROJECT_NAME = Kishna Glista
+
+# output
OUTPUT_DIRECTORY = html
+
+# settings
WARNINGS = YES
+
+# input
INPUT = ../../src
-FILE_PATTERNS = *.hh */*.hh
+FILE_PATTERNS = *.hh *.cc
+EXCLUDE_PATTERNS = */.svn/*
+RECURSIVE = YES
+
+# system stuff
PERL_PATH = /usr/bi/perl
--- a/src/Network/Address.hh Mon Dec 08 12:46:37 2008 +0000
+++ b/src/Network/Address.hh Mon Dec 08 15:02:05 2008 +0000
@@ -3,9 +3,14 @@
#include <ClanLib/Network/Socket/ip_address.h>
+/**
+ * We use ClanLib's IPAddress API, but with our own name
+ */
typedef CL_IPAddress NetworkAddress;
-// Network.cc
+/**
+ * Formatted as [<addr>:<port>]
+ */
std::ostream& operator<< (std::ostream &s, const NetworkAddress &addr);
#endif /* NETWORK_ADDRESS_HH */
--- a/src/Network/Buffer.hh Mon Dec 08 12:46:37 2008 +0000
+++ b/src/Network/Buffer.hh Mon Dec 08 15:02:05 2008 +0000
@@ -6,71 +6,123 @@
#include <cassert>
-/*
+/**
* Minimum chunk size to avoid handling single bytes at a time (for resize, mainly)
*/
const size_t NETWORK_BUFFER_CHUNK_SIZE = 1024;
+/**
+ * Base class of errors thrown by NetworkBuffer* methods
+ */
class NetworkBufferError : public Error {
public:
NetworkBufferError (const std::string &message) : Error(message) { }
};
-/*
- * Base buffer operations for uffered socket send/recv
+/**
+ * Base buffer-manipulation operations for buffered socket send/recv
*/
class NetworkBufferBase {
protected:
- // the socket that we use
+ /** The socket that we use */
NetworkSocket socket;
+
+ /** The buffer itself */
+ char *buf;
- char *buf;
+ /** Buffer size and current read/write offset */
size_t size, offset;
public:
+ /**
+ * Allocate buf using the given initial size, and set offset to zero
+ */
NetworkBufferBase (NetworkSocket &socket, size_t size_hint);
+
+ /**
+ * Free()'s the buf
+ */
~NetworkBufferBase (void);
private:
+ /**
+ * No copying, these are undefined
+ */
NetworkBufferBase (const NetworkBufferBase ©);
NetworkBufferBase& operator= (const NetworkBufferBase ©);
protected:
+ /**
+ * Resize the buffer, allocating enough new space to hold <item_size> bytes at the end, and leaving any
+ * existing data at the beginning in-place
+ *
+ * @param item_size the number of bytes that must fit at the end of the buffer
+ */
void resize (size_t item_size);
+
+ /**
+ * Trim the buffer, discarding <prefix_size> bytes at the beginning. Updates offset to match.
+ *
+ * @param prefix_size the number of bytes to discard
+ */
void trim (size_t prefix_size);
};
-/*
+/**
* Buffered prefix-len socket input
*/
class NetworkBufferInput : public NetworkBufferBase {
public:
+ /**
+ * @see NetworkBufferBase
+ */
NetworkBufferInput (NetworkSocket &socket, size_t size_hint);
private:
- /*
- * Attempts to recv the given number of bytes, returning true on success
+ /**
+ * Attempts to recv the given number of bytes into our buf, returning true on success
+ *
+ * @param item_size minimum number of bytes of data that we need in the buffer
+ * @return bool true if the buffer now contains at least item_size bytes
*/
bool try_read (size_t item_size);
- /*
- * Returns true if the buffer contains at least the given amount of data
+ /**
+ * Tests if the buffer contains at least the given amount of data, but doesn't recv or anything
+ *
+ * @param data_size number of bytes that we are expecting
+ * @return bool true if the buffer contains at least data_size bytes
*/
bool have_data (size_t data_size);
public:
- /*
- * Attempts to read the length prefix into val_ref, returning true on success
+ // @{
+ /**
+ *
+ * Attempts to read the length prefix into val_ref, returning true on success, false if there's not enough data
+ * in the buffer
+ *
+ * @param val_ref stores the value read here if we have it
+ * @return bool was val_ref set
*/
bool peek_prefix (uint16_t &val_ref);
bool peek_prefix (uint32_t &val_ref);
+ // @}
- /*
- * This attempts to collect the prefix + data into our buffer, and then returns the length and a pointer to the
- * internal memory buffer. Use flush_data when done with the data
+ /**
+ * This attempts to read a length-prefix of the given type (using peek_prefix), and then the associated data.
+ * If succesful, this sets prefix to the length of the data, and buf_ref to point at the data inside our buffer
+ * and returns true, else false.
+ *
+ * This will try and consume data from the buffer, or recv if needed.
+ *
+ * @param prefix stores the data length here
+ * @param buf_ref stores a pointer to the data here
+ * @return bool true if we have the full data, false if we need to wait for more data on the socket
+ *
+ * @see peek_prefix
+ * @see flush_data
*/
-
- // XXX: template definition moved here from .cc
template <typename PrefixType> bool peek_data (PrefixType &prefix, char *&buf_ref) {
size_t missing = 0;
@@ -108,7 +160,13 @@
// return
return true;
}
-
+
+ /**
+ * This flushes a prefix-length worth of data from the buffer, i.e. it first reads the prefix, and then trims
+ * the prefix and the data away. Don't call this unless you *know* that the buffer contains enough data.
+ *
+ * @see peek_data
+ */
template <typename PrefixType> void flush_data (void) {
PrefixType prefix;
@@ -120,31 +178,44 @@
}
};
-/*
+/**
* Buffered prefix-len socket output
*/
class NetworkBufferOutput : public NetworkBufferBase {
public:
+ /**
+ * @see NetworkBufferBase
+ */
NetworkBufferOutput (NetworkSocket &socket, size_t size_hint);
private:
- /*
- * If our buffer is empty, fast-path the given buf_ptr directly to send(), else copy the remaining
- * portion to our buffer for later use with flush_write
+ /**
+ * Write the given data to the socket, either now of later.
+ *
+ * If our buffer is empty, fast-path the given buf_ptr directly to send(), then copy the remaining portion to
+ * our buffer for later use with flush_write.
+ *
+ * @param buf_ptr the data that we need to send
+ * @param buf_size number of bytes in buf_ptr
*/
void push_write (char *buf_ptr, size_t buf_size);
public:
- /*
- * Try and send() stuff out of our buffer, or ignore if it's empty
+ /**
+ * If we have data in our buffer, flush it out using send().
*/
void flush_write (void);
- /*
- * push_write, first the given prefix and then the buf (which contains <prefix> bytes of data)
+ // @{
+ /**
+ * Write out the given data, writing first the prefix, and then the data itself, using push_write.
+ *
+ * @param buf the data to write
+ * @param prefix the amount of data
*/
void write_prefix (char *buf, uint16_t prefix);
void write_prefix (char *buf, uint32_t prefix);
+ // @}
};
#endif
--- a/src/Network/Packet.hh Mon Dec 08 12:46:37 2008 +0000
+++ b/src/Network/Packet.hh Mon Dec 08 15:02:05 2008 +0000
@@ -5,6 +5,9 @@
#include "../Vector.hh"
#include "../Error.hh"
+/**
+ * Base class of errors thrown by NetworkPacket* methods
+ */
class NetworkPacketError : public Error {
public:
NetworkPacketError (const std::string &message) : Error(message) { }
@@ -13,104 +16,190 @@
// forward-declare for write_packet
class NetworkPacketBuffer;
-/*
+/**
* Read-interface for network packets
*/
class NetworkPacketInput {
public:
- /*
- * Copies len bytes from the packet to ptr, first testing that they exist
+ /**
+ * Abstract method that copies len bytes from the packet to ptr, first testing that they exist
*/
- virtual void read (void *ptr, size_t len) = 0;
+ virtual void read (
+ void *ptr, //<<< where to copy
+ size_t len //<<< number of bytes to copy
+ ) = 0;
- /*
+ /**
* Convenience function to read() and return the value of the given type
+ *
+ * @return T The value
*/
template <typename T> T read_val (void);
- // thse handle network-endianlness
+ /**
+ * @defgroup read_* Read methods
+ * Collection of methods to write out simple types, these convert from network-endianness and return the value
+ *
+ * @{
+ */
+
+ /** 32-bit unsigned int */
uint32_t read_uint32 (void);
+
+ /** 16-bit unsigned int */
uint16_t read_uint16 (void);
+
+ /** 8-bit unsigned int */
uint8_t read_uint8 (void);
+ /** 32-bit signed int */
int32_t read_int32 (void);
+
+ /** 16-bit signed int */
int16_t read_int16 (void);
+
+ /** 8-bit signed int */
int8_t read_int8 (void);
+ /** 32-bit float */
float read_float32 (void);
+
+ /**
+ * @}
+ */
+ /**
+ * Read a Vector from the packet:
+ * float32 vec_x
+ * float32 vec_y
+ *
+ * @return Vector (vec_x, vec_y)
+ */
Vector read_vector (void);
};
-/*
+/**
* Write-interface for network packets
*/
class NetworkPacketOutput {
public:
- /*
- * Copies len bytes from ptr to the packet, first testing that they fit
+ /**
+ * Abstract method that copies len bytes from ptr to the packet, first testing that they fit
*/
- virtual void write (const void *ptr, size_t len) = 0;
+ virtual void write (
+ const void *ptr, //<<< where to copy from
+ size_t len //<<< number of bytes to copy
+ ) = 0;
- /*
+ /**
* Convenience function to write() the value of the given type-value
+ *
+ * @param val The value
*/
template <typename T> void write_val (const T &val);
-
- // thse handle network-endianlness
+
+ /**
+ * @defgroup write* Write methods
+ * Collection of methods to write out simple types, these convert the given value to network-byte-order
+ *
+ * @{
+ */
void write_uint32 (uint32_t val);
void write_uint16 (uint16_t val);
void write_uint8 (uint8_t val);
-
void write_int32 (int32_t val);
void write_int16 (int16_t val);
void write_int8 (int8_t val);
+ void write_float32 (float val);
- void write_float32 (float val);
+ /**
+ * @}
+ */
+ /**
+ * Write a vector to the packet:
+ * float32 vec_x
+ * float32 vec_y
+ *
+ * @param vec a Vector(vec_x, vec_y)
+ */
void write_vector (const Vector &vec);
- /*
- * This copies the contents of the given packet into this packet
+ /**
+ * This write()s the contents of the given NetworkPacketBuffer to this packet.
+ *
+ * @param pkt the sub-packet to write()
*/
void write_packet (const NetworkPacketBuffer &pkt);
};
-/*
- * Implements the in-memory seekable buffer used by NetworkPackets.
+/**
+ * Implements an in-memory seekable buffer used by NetworkPackets
+ *
+ * @see NetworkPacketInput
+ * @see NetworkPacketOutput
*/
class NetworkPacketBuffer : public NetworkPacketInput, public NetworkPacketOutput {
protected:
- // the pointer to the buffer
+ /**
+ * Pointer to the packet data
+ */
char *buf_ptr;
// the buffer size, the amount of data in the buffer, and the current read/write offset
- size_t buf_size, data_size, offset;
+ /**
+ * The size of the memory region pointed to by buf_ptr
+ */
+ size_t buf_size;
- /*
- * Assert that the given number of bytes fits into the buffer. Throws NetworkPacketError if not.
+ /**
+ * The number of bytes of read()-able data stored at buf_ptr
+ */
+ size_t data_size;
+
+ /**
+ * The current offset at which to run the next read/write
+ */
+ size_t offset;
+
+ /**
+ * Assert that the given number of bytes fits into the buffer at offset. Throws NetworkPacketError if not.
*
* The default implementation just checks offset and buf_size
+ *
+ * @param item_size the size of the item that should to be written
*/
virtual void check_write_size (size_t item_size);
- /*
- * Assert that the give number of bytes is available from the buffer. Throws NetworkPacketError if not
+ /**
+ * Assert that the given number of bytes is available from the buffer. Throws NetworkPacketError if not
*
* The default implementation just checks offset and data_size
+ *
+ * @param item_size the size of the item that should be read
*/
virtual void check_read_size (size_t item_size);
public:
- /*
- * Construct the NetworkPacketBuffer using the given initial buf_ptr and buf_size
+ /**
+ * Construct the NetworkPacketBuffer using the given buf_ptr, buf_size and data_size
*/
NetworkPacketBuffer (char *buf_ptr, size_t buf_size, size_t data_size);
- /*
- * These memcpy() into/out of the buf_ptr, using ceck_read/write_size
+ /**
+ * Copy bytes from the packet buffer to ptr using memcpy(), calling check_read_size first.
+ *
+ * @param ptr where to copy the data to
+ * @param len number of bytes to copy
*/
virtual void read (void *ptr, size_t len);
+
+ /**
+ * Copy bytes from ptr to the packet buffer using memcpy(), calling check_write_size first
+ *
+ * @param ptr where to copy the data from
+ * @param len number of bytes to copy
+ */
virtual void write (const void *ptr, size_t len);
/*
@@ -121,39 +210,55 @@
size_t get_data_size (void) const { return data_size; }
size_t get_buf_size (void) const { return buf_size; }
- /*
- * Used by the socket code after recv() to mark how many bytes of data the buffer has
+ /**
+ * If the contents of buf_ptr is replaced with a new packet, call this to update offset/data_size
+ *
+ * @param size new amount of data in the buffer
*/
void set_data_size (size_t size) { offset = 0; data_size = size; }
};
-/*
+/**
* The common case is a packet that fits in a single UDP packet, so this just uses a static buffer of a fixed size,
* NETWORK_PACKET_SIZE.
+ *
+ * @see NetworkPacketBuffer
+ * @see NETWORK_PACKET_SIZE
*/
class NetworkPacket : public NetworkPacketBuffer {
private:
+ /**
+ * The static buffer, NETWORK_PACKET_SIZE bytes
+ */
char _buf[NETWORK_PACKET_SIZE];
public:
NetworkPacket (void);
};
-/*
- * This is intended for sending bigger packets via TCP; the buffer is allocated on the heap.
+/**
+ * This is intended for sending bigger packets via TCP; a buffer of the given size is allocated on the heap.
*
- * XXX: let the buffer grow as well
+ * @see NetworkPacketBuffer
*/
class BigNetworkPacket : public NetworkPacketBuffer {
public:
+ /**
+ * Allocates a buffer of the given size on the heap and uses it for NetworkPacketBuffer
+ */
BigNetworkPacket (size_t size);
private:
- // no copies
+ /**
+ * Object must not be copied
+ */
BigNetworkPacket (const BigNetworkPacket &pkt);
BigNetworkPacket& operator= (const BigNetworkPacket &pkt);
public:
+ /**
+ * Frees the heap buffer
+ */
virtual ~BigNetworkPacket (void);
};
--- a/src/Network/Socket.hh Mon Dec 08 12:46:37 2008 +0000
+++ b/src/Network/Socket.hh Mon Dec 08 15:02:05 2008 +0000
@@ -7,9 +7,14 @@
#include <cerrno>
#include <cstring>
+/**
+ * We use ClanLib's Socket API, but with our own name
+ */
typedef CL_Socket NetworkSocket;
-// Network.cc
+/**
+ * Base class for expcetions thrown by socket methods
+ */
class NetworkSocketError : public Error {
protected:
std::string build_str (const NetworkSocket &socket, const char *op, const char *err);
@@ -17,12 +22,18 @@
NetworkSocketError (const NetworkSocket &socket, const char *op, const char *err);
};
+/**
+ * Errno-enabled exception, most common type of NetworkSocketError
+ */
class NetworkSocketOSError : public NetworkSocketError {
public:
NetworkSocketOSError (const NetworkSocket &socket, const char *op) :
NetworkSocketError(socket, op, strerror(errno)) { }
};
+/**
+ * Recv returned EOF
+ */
class NetworkSocketEOFError : public NetworkSocketError {
public:
NetworkSocketEOFError (const NetworkSocket &socket, const char *op) :