inline code documentation

svn path=/trunk/externals/iem/iemnet/; revision=13311

4 files changed, 228 insertions, 34 deletions

diff --git a/Makefile b/Makefile
index 7d9b730..90d8b36 100644
--- a/Makefile
+++ b/Makefile
@@ -52,7 +52,7 @@ INSTALL_FILE    = $(INSTALL) -p -m 644
 INSTALL_LIB     = $(INSTALL) -p -m 644 -s
 INSTALL_DIR     = $(INSTALL) -p -m 755 -d
 
-CFLAGS = -DPD -I$(PD_PATH)/src -Wall -W -g
+CFLAGS = -DPD -I$(PD_PATH)/src -Wall -W -Wno-unused -g 
 LDFLAGS =  
 LIBS = 
 ALLSOURCES := $(SOURCES) $(SOURCES_android) $(SOURCES_cygwin) $(SOURCES_macosx) \
diff --git a/iemnet.h b/iemnet.h
index 511a0f1..c8598d8 100644
--- a/iemnet.h
+++ b/iemnet.h
@@ -52,7 +52,12 @@ EXTERN void sys_rmpollfn(int fd);
 # include <sys/socket.h>
 #endif
 
-/* sender */
+/* iemnet_data.c */
+
+/**
+ * chunk of data as sent to a socket or received from it
+ * for received data, this might additionally hold the originator (if available)
+ */
 typedef struct _iemnet_chunk {
   unsigned char* data;
   size_t size;
@@ -61,59 +66,161 @@ typedef struct _iemnet_chunk {
   unsigned short port;
 } t_iemnet_chunk;
 
+/**
+ * free a "chunk" (de-allocate memory,...)
+ */
 void iemnet__chunk_destroy(t_iemnet_chunk*);
+
+/**
+ * initialize a "chunk" (allocate memory,...) of fixed size
+ * receiver address will be set to 0
+ *
+ * \param size of the chunk (data will be zeroed out)
+ * \return a new chunk of given size
+ */
 t_iemnet_chunk*iemnet__chunk_create_empty(int);
-t_iemnet_chunk*iemnet__chunk_create_data(int, unsigned char*);
-t_iemnet_chunk*iemnet__chunk_create_dataaddr(int, unsigned char*, struct sockaddr_in*addr);
-t_iemnet_chunk*iemnet__chunk_create_list(int, t_atom*);
-t_iemnet_chunk*iemnet__chunk_create_chunk(t_iemnet_chunk*);
+/**
+ * initialize a "chunk" (allocate memory,...) with given data
+ * receiver address will be set to 0
+ *
+ * \param size of data
+ * \param data of size
+ * \return a new chunk that holds a copy of data
+ */
+t_iemnet_chunk*iemnet__chunk_create_data(int size, unsigned char*data);
+/**
+ * initialize a "chunk" (allocate memory,...) with given data from specified address
+ * \param size of data
+ * \param data of size
+ * \param addr originating address (can be NULL)
+ * \return a new chunk that holds a copy of data
+ */
+t_iemnet_chunk*iemnet__chunk_create_dataaddr(int size, unsigned char*data, struct sockaddr_in*addr);
+/**
+ * initialize a "chunk" (allocate memory,...) with given data
+ * receiver address will be set to 0
+ *
+ * \param argc size of list
+ * \param argv list of atoms containing only "bytes" (t_floats [0..255])
+ * \return a new chunk that holds a copy of the list data
+ */
+t_iemnet_chunk*iemnet__chunk_create_list(int argc, t_atom*argv);
+/**
+ * initialize a "chunk" (allocate memory,...) from another chunk
+ *
+ * \param src the source chunk
+ * \return a new chunk that holds a copy of the source data
+ */
+t_iemnet_chunk*iemnet__chunk_create_chunk(t_iemnet_chunk*source);
+
+
+/* iemnet_sender.c */
 
-/* sender */
-#define t_iemnet_sender struct _iemnet_sender
+/**
+ * opaque data type used for sending data over a socket
+ */
+typedef struct _iemnet_sender t_iemnet_sender;
 EXTERN_STRUCT _iemnet_sender;
 
+/**
+ * create a sender to a given socket
+ *
+ * \param sock a previously opened socket
+ * \return pointer to a sender object
+ * \note the socket must be writeable
+ */
 t_iemnet_sender*iemnet__sender_create(int sock);
+/**
+ * destroy a sender to a given socket
+ * destroying a sender will free all resources of the sender
+ *
+ * \param pointer to a sender object to be destroyed
+ *
+ * \note  it will also close() the socket
+ */
 void iemnet__sender_destroy(t_iemnet_sender*);
 
+/**
+ * send data over a socket
+ *
+ * \param pointer to a sender object 
+ * \param pointer to a chunk of data to be sent
+ * \return the current fill state of the send buffer
+ */
 int iemnet__sender_send(t_iemnet_sender*, t_iemnet_chunk*);
 
-int iemnet__sender_getlasterror(t_iemnet_sender*);
-int iemnet__sender_getsockopt(t_iemnet_sender*, int level, int optname, void      *optval, socklen_t*optlen);
-int iemnet__sender_setsockopt(t_iemnet_sender*, int level, int optname, const void*optval, socklen_t optlen);
+/**
+ * query the fill state of the send buffer
+ *
+ * \param pointer to a sender object 
+ * \return the current fill state of the send buffer
+ */
+int iemnet__sender_getsize(t_iemnet_sender*);
 
 
-/* receiver */
-#define t_iemnet_receiver struct _iemnet_receiver
-EXTERN_STRUCT _iemnet_receiver;
+/* iemnet_receiver.c */
 
+/**
+ * opaque data type used for receiving data from a socket
+ */
+typedef struct _iemnet_receiver t_iemnet_receiver;
+EXTERN_STRUCT _iemnet_receiver;
+/**
+ * callback function for receiving
+ * whenever data arrives at the socket, a callback will be called synchronously
+ */
 typedef void (*t_iemnet_receivecallback)(void*userdata, 
 					 t_iemnet_chunk*rawdata,
 					 int argc, t_atom*argv);
 
 /**
- * create a receiver object: whenever something is received on the socket,
- * the callback is called with the payload
+ * create a receiver object
+ *
+ *  whenever something is received on the socket, the callback is called with the payload in the main thread of the caller
+ *
+ * \param sock the (readable) socket to receive from
+ * \param data user data to be passed to callback
+ * \param callback a callback function that is called on the caller's side
+ *
+ * \note the callback will be scheduled in the caller's thread with clock_delay()
  */
 t_iemnet_receiver*iemnet__receiver_create(int sock, void*data, t_iemnet_receivecallback callback);
+/**
+ * destroy a receiver at a given socket
+ * destroying a receiver will free all resources of the receiver
+ *
+ * \param pointer to a receiver object to be destroyed
+ *
+ * \note  it will also close() the socket
+ */
 void iemnet__receiver_destroy(t_iemnet_receiver*);
 
-
+/**
+ * query the fill state of the receive buffer
+ *
+ * \param pointer to a receiver object 
+ * \return the current fill state of the receive buffer
+ */
+int iemnet__receiver_getsize(t_iemnet_receiver*);
 
 
 
 /* convenience functions */
 
-/* output the address */
+/**
+ * output the address  (IP, port)
+ * the given address is first output through the status_outlet as a "host" message
+ * and then as a list through the address_outlet
+ *
+ * \param status_outlet outlet for general status messages
+ * \param address_outlet outlet for addresses only
+ * \param address the host ip
+ * \param port the host port
+ *
+ * \note the address will be output as a 5 element list, with the 1st 4 elements denoting the quads of the IP address (as bytes) and the last element the port
+ */
 void iemnet__addrout(t_outlet*status_outlet, t_outlet*address_outlet, long address, unsigned short port);
 
-
-
-
-
-
-
-
-
 #if defined(_MSC_VER)
 # define snprintf _snprintf
 # define IEMNET_EXTERN __declspec(dllexport) extern
@@ -129,7 +236,12 @@ void iemnet__addrout(t_outlet*status_outlet, t_outlet*address_outlet, long addre
 #endif
 
 
-
+/**
+ * \fn void DEBUG(const char* format,...);
+ *
+ * \brief debug output
+ * \note this will only take effect if DEBUG is not undefined
+ */
 #ifdef DEBUG
 # undef DEBUG
 # define DEBUG startpost("[%s:%d]", __FUNCTION__, __LINE__); post
@@ -139,7 +251,4 @@ static void debug_dummy(const char *format, ...)  {;}
 #endif
 
 
-
-
-
 #endif /* INCLUDE_IEMNET_H_ */
diff --git a/iemnet_data.c b/iemnet_data.c
index e7204ce..ce19693 100644
--- a/iemnet_data.c
+++ b/iemnet_data.c
@@ -187,7 +187,7 @@ typedef struct _node {
   t_iemnet_chunk*data;
 } t_node;
 
-typedef struct _queue {
+struct _iemnet_queue {
   t_node* head; /* = 0 */
   t_node* tail; /* = 0 */
   pthread_mutex_t mtx;
@@ -195,7 +195,7 @@ typedef struct _queue {
 
   int done; // in cleanup state
   int size;
-} t_iemnet_queue;
+};
 
 
 int queue_push(
diff --git a/iemnet_data.h b/iemnet_data.h
index 60a625b..45d1487 100644
--- a/iemnet_data.h
+++ b/iemnet_data.h
@@ -29,7 +29,9 @@
 
 /* ---------------------------------------------------------------------------- */
 
-
+/**
+ * a resizable list of float-only atoms
+ */
 typedef struct _iemnet_floatlist {
   t_atom*argv;
   size_t argc;
@@ -37,8 +39,91 @@ typedef struct _iemnet_floatlist {
   size_t size; // real size (might be bigger than argc)
 } t_iemnet_floatlist;
 
+/**
+ * create a list of float-only atoms
+ *
+ * \param size initial size of the floatlist
+ * \return pointer to a float-atom list or NULL of creation failed
+ */
+t_iemnet_floatlist*iemnet__floatlist_create(unsigned int size);
+/**
+ * destroy a list of float-only atoms
+ *
+ * \param  pointer to a float-atom list
+ */
+void iemnet__floatlist_destroy(t_iemnet_floatlist*cl);
 
 
-#define t_iemnet_queue struct _iemnet_queue
+/**
+ * convert a data chunk to a Pd-list of A_FLOATs
+ * the destination list will eventually be resized if it is too small to hold the chunk
+ *
+ * \param c the chunk to convert 
+ * \param dest the destination list
+ * \return the destination list if all went well, else NULL
+ */
+t_iemnet_floatlist*iemnet__chunk2list(t_iemnet_chunk*c, t_iemnet_floatlist*dest);
+
+
+/**
+ * opaque type for a thread safe queue (FIFO)
+ */
+typedef struct _iemnet_queue t_iemnet_queue;
 EXTERN_STRUCT _iemnet_queue;
 
+/**
+ * push data to the FIFO (queue)
+ *
+ * \param q the queue to push to
+ * \param d the pushed data (the queue will only store the pointer to the data; so don't free it yet)
+ * \return the fill state of the queue after the push
+ *
+ * \note thread safe
+ */
+int queue_push(t_iemnet_queue* const q, t_iemnet_chunk* const d);
+/**
+ * \brief pop data from the FIFO (queue), blocking
+ *
+ *  pops data from the stack; 
+ *  if the stack is empty, this function will block until data is pushed to the stack
+ *  if the queue is finalized, this function will return immediately with NULL
+ *
+ * \param q the queue to pop from
+ * \return pointer to the popped data; the caller is responsible for freeing the chunk
+ *
+ * \note thread safe
+ */
+t_iemnet_chunk* queue_pop_block(t_iemnet_queue* const q);
+/**
+ * pop data from the stack (queue), non-blocking
+ *
+ * pops data from the stack; if the stack is empty, this function will immediately return NULL
+ *
+ * \param q the queue to pop from
+ * \return pointer to the popped data or NULL; the caller is responsible for freeing the chunk
+ *
+ * \note thread safe
+ */
+t_iemnet_chunk* queue_pop_noblock(t_iemnet_queue* const);
+/**
+ * initiate cleanup process
+ *
+ * unblocks all blocking calls to queue_pop_block(t_iemnet_queue* const q);
+ *
+ * \param q the queue to unblock
+ */
+void queue_finish(t_iemnet_queue* q);
+/**
+ * destroy queue (FIFO)
+ *
+ * releases all data in the queue (by calling iemnet__chunk_destroy()) and then frees all other ressources attached to the queue
+ *
+ * \param q the queue to destroy
+ */
+void queue_destroy(t_iemnet_queue* q);
+/**
+ * create a queue (FIFO)
+ *
+ * \return the newly created queue; if something went wrong NULL is returned
+ */
+t_iemnet_queue* queue_create(void);