Added comments

src/common/slurm_protocol_api.c

@@ -18,11 +18,12 @@ extern int errno ;
 /* #DEFINES */
 
 
-/***** high level routines */
+/************************/
 /***** msg functions */
+/************************/
 
 /* In the socket implementation it creates a socket, binds to it, and listens for connections.
- * In the mongo implemenetation is should just create a mongo socket , bind and return.
+ * In the mongo implemenetation is should just create a mongo socket , binds and return.
  * slurm_address 	- for now it is really just a sockaddr_in
  * slurm_fd		- file descriptor of the connection created
  */
@@ -33,8 +34,6 @@ slurm_fd slurm_init_msg_engine_port ( uint16_t port )
 	return _slurm_init_msg_engine ( & slurm_address ) ;
 }
 
-/***** msg functions */
-
 /* In the socket implementation it creates a socket, binds to it, and listens for connections.
  * In the mongo implemenetation is should just create a mongo socket , bind and return.
  * slurm_address 	- for now it is really just a sockaddr_in
@@ -54,12 +53,18 @@ int slurm_shutdown_msg_engine ( slurm_fd open_fd )
 	return _slurm_close ( open_fd ) ;
 }
 
+/* just calls close on an established msg connection
+ * open_fd	- an open file descriptor
+ * int	- the return code
+ */
 int slurm_shutdown_msg_conn ( slurm_fd open_fd ) 
 {
 	return _slurm_close ( open_fd ) ;
 }
 
-/* calls connect to make a connection-less connection to the destination msg engine
+/* In the bsd implementation it creates a SOCK_STREAM socket and calls connect on it
+ * In the mongo implementation it creates a SOCK_DGRAM socket and calls connect on it
+ * a SOCK_DGRAM socket called with connect is defined to only receive messages from the address/port pair argument of the connect call
  * slurm_address 	- for now it is really just a sockaddr_in
  * int	- the return code
  */
@@ -68,7 +73,7 @@ slurm_fd slurm_open_msg_conn ( slurm_addr * slurm_address )
 	return _slurm_open_msg_conn ( slurm_address ) ;
 }
 
-/* calls connect to make a connection-less connection to the the primary or secondary slurmctld message engine
+/* calls connect to make a connection-less datagram connection to the the primary or secondary slurmctld message engine
  * slurm_address 	- for now it is really just a sockaddr_in
  * int	- the return code
  */
@@ -95,7 +100,8 @@ slurm_fd slurm_open_controller_conn ( )
 	return connection_fd ;
 }
 
-/* calls connect to make a connection-less connection to the destination msg engine
+/* In the bsd implmentation maps directly to a accept call 
+ * In the mongo it returns the open_fd and is essentially a no-op function call
  * open_fd		- file descriptor to accept connection on
  * slurm_address 	- for now it is really just a sockaddr_in
  * int	- the return code
@@ -105,8 +111,8 @@ slurm_fd slurm_accept_msg_conn ( slurm_fd open_fd , slurm_addr * slurm_address )
 	return _slurm_accept_msg_conn ( open_fd , slurm_address ) ;
 }
 
-
-/* calls connect to make a connection-less connection to the destination msg engine
+/* In the bsd implmentation maps directly to a close call, to close the socket that was accepted
+ * In the mongo it is a no-op (  slurm_shutdown_msg_engine should be called to close the mongo socket since there is no "accept" phase for datagrams
  * open_fd		- file descriptor to accept connection on
  * int	- the return code
  */
@@ -119,7 +125,6 @@ int slurm_close_accepted_conn ( slurm_fd open_fd )
 /*
  * note that a memory is allocated for the returned msg and must be freed at some point 
  * open_fd 		- file descriptor to receive msg on
- * source_address 	- address of the source of the msg for now it is really just a sockaddr_in
  * msg 		- a slurm msg struct
  * int		- size of msg received in bytes before being unpacked
  */
@@ -159,7 +164,6 @@ int slurm_receive_msg ( slurm_fd open_fd , slurm_msg_t * msg )
  * if unable to contant the primary slurmctld attempts will be made to contact the backup controller
  * 
  * open_fd	- file descriptor to send msg on
- * msg_type	- type of msg to be sent ( see slurm_protocol_defs.h for msg types )
  * msg	- a slurm msg struct
  * int	- size of msg sent in bytes
  */
@@ -190,8 +194,6 @@ int slurm_send_controller_msg ( slurm_fd open_fd , slurm_msg_t * msg )
 /* sends a message to an arbitrary node
  *
  * open_fd		- file descriptor to send msg on
- * destination_address	- address of destination nodes
- * msg_type		- type of msg to be sent ( see slurm_protocol_defs.h for msg types )
  * msg			- a slurm msg struct
  * int		- size of msg sent in bytes
  */
@@ -324,7 +326,9 @@ int slurm_send_node_buffer ( slurm_fd open_fd , slurm_addr * destination_address
 	return rc ;
 }
 
+/************************/
 /***** stream functions */
+/************************/
 slurm_fd slurm_listen_stream ( slurm_addr * slurm_address )
 {
 	return _slurm_listen_stream ( slurm_address ) ;
@@ -355,6 +359,9 @@ int slurm_close_stream ( slurm_fd open_fd )
 	return _slurm_close ( open_fd ) ;
 }
 
+/************************/
+/***** slurm addr functions */
+/************************/
 /* sets/gets the fields of a slurm_addr */
 void slurm_set_addr_uint ( slurm_addr * slurm_address , uint16_t port , uint32_t ip_address )
 {
@@ -382,6 +389,7 @@ void slurm_get_addr ( slurm_addr * slurm_address , uint16_t * port , char * host
 }
 
 /* slurm msg type */
+/* frees the inner message data then frees the msg struct */
 void slurm_msg_destroy ( slurm_msg_t * location , int destroy_data )
 {
 	if ( destroy_data )

src/common/slurm_protocol_pack.c

@@ -7,6 +7,12 @@
 #include <src/common/log.h>
 #include <src/slurmctld/slurmctld.h>
 
+/* pack_header
+ * packs a slurm protocol header that proceeds every slurm message
+ * header 	- the header structure to pack
+ * buffer	- destination of the pack, note buffer will be incremented by underlying pack routines
+ * length	- length of buffer, note length will be decremented by underlying pack routines
+ */
 void pack_header ( header_t * header, char ** buffer , uint32_t * length )
 {
 	pack16 ( header -> version , ( void ** ) buffer , length ) ;
@@ -15,6 +21,12 @@ void pack_header ( header_t * header, char ** buffer , uint32_t * length )
 	pack32 ( header -> body_length , ( void ** ) buffer , length ) ;
 }
 
+/* unpack_header
+ * unpacks a slurm protocol header that proceeds every slurm message
+ * header 	- the header structure to unpack
+ * buffer	- destination of the pack, note buffer will be incremented by underlying unpack routines
+ * length	- length of buffer, note length will be decremented by underlying unpack routines
+ */
 void unpack_header ( header_t * header , char ** buffer , uint32_t * length )
 {
 	unpack16 ( & header -> version , ( void ** ) buffer , length ) ;
@@ -23,6 +35,12 @@ void unpack_header ( header_t * header , char ** buffer , uint32_t * length )
 	unpack32 ( & header -> body_length , ( void ** ) buffer , length ) ;
 }
 
+/* pack_msg
+ * packs a slurm protocol mesg body
+ * header 	- the body structure to pack
+ * buffer	- destination of the pack, note buffer will be incremented by underlying pack routines
+ * length	- length of buffer, note length will be decremented by underlying pack routines
+ */
 int pack_msg ( slurm_msg_t const * msg , char ** buffer , uint32_t * buf_len )
 {
 	switch ( msg -> msg_type )
@@ -94,6 +112,12 @@ int pack_msg ( slurm_msg_t const * msg , char ** buffer , uint32_t * buf_len )
 	return 0 ;
 }
 
+/* unpack_msg
+ * unpacks a slurm protocol msg body
+ * header 	- the body structure to unpack
+ * buffer	- destination of the pack, note buffer will be incremented by underlying unpack routines
+ * length	- length of buffer, note length will be decremented by underlying unpack routines
+ */
 int unpack_msg ( slurm_msg_t * msg ,char ** buffer , uint32_t * buf_len )
 {
 	switch ( msg-> msg_type )
@@ -179,7 +203,6 @@ void unpack_node_registration_status_msg ( node_registration_status_msg_t * msg
 	unpack32 ( & msg -> temporary_disk_space , ( void ** ) buffer , length ) ;
 }
 
-
 int unpack_build_info ( struct build_buffer **build_buffer_ptr, void * buffer , int buffer_size )
 {	
 	uint16_t uint16_tmp;
@@ -229,6 +252,12 @@ int unpack_build_info ( struct build_buffer **build_buffer_ptr, void * buffer ,
 	return 0;
 }
 
+/* pack_job_desc
+ * packs a job_desc struct 
+ * header 	- the body structure to pack
+ * buf_ptr	- destination of the pack, note buffer will be incremented by underlying pack routines
+ * buffer_size	- length of buffer, note length will be decremented by underlying pack routines
+ */
 void pack_job_desc ( job_desc_t * job_desc_ptr, void ** buf_ptr , int * buffer_size )
 {	
 	/* load the data values */
@@ -260,6 +289,12 @@ void pack_job_desc ( job_desc_t * job_desc_ptr, void ** buf_ptr , int * buffer_s
 
 }
 
+/* unpack_msg
+ * unpacks a job_desc struct
+ * header 	- the body structure to unpack
+ * buf_ptr	- destination of the pack, note buffer will be incremented by underlying unpack routines
+ * buffer_size	- length of buffer, note length will be decremented by underlying unpack routines
+ */
 void unpack_job_desc ( job_desc_t **job_desc_buffer_ptr, void ** buf_ptr , int * buffer_size )
 {	
 	uint16_t uint16_tmp;
@@ -304,13 +339,13 @@ void unpack_job_desc ( job_desc_t **job_desc_buffer_ptr, void ** buf_ptr , int *
 }
 
 /* template 
-void pack_ ( char ** buffer , uint32_t * length , * msg )
+void pack_ ( * msg , char ** buffer , uint32_t * length )
 {
 	pack16 ( msg -> , buffer , length ) ;
 	pack32 ( msg -> , buffer , length ) ;
 }
 
-void unpack_ ( char ** buffer , uint32_t * length , * messge )
+void unpack_ ( * msg , char ** buffer , uint32_t * length )
 {
 	unpack16 ( & msg -> , buffer , length ) ;
 	unpack32 ( & msg -> , buffer , length ) ;