From c4836ce4a969a6493606fe1c136d654c8777d6ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?IOhannes=20m=20zm=C3=B6lnig?= Date: Tue, 30 Mar 2010 09:06:54 +0000 Subject: inline code documentation svn path=/trunk/externals/iem/iemnet/; revision=13311 --- Makefile | 2 +- iemnet.h | 167 ++++++++++++++++++++++++++++++++++++++++++++++++---------- iemnet_data.c | 4 +- iemnet_data.h | 89 ++++++++++++++++++++++++++++++- 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 #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); -- cgit v1.2.1