Added additional documentation and made sure that all functions that return a fd

had a return type of slurm_fd

src/common/slurm_protocol_api.c

@@ -14,26 +14,37 @@ uint32_t debug = false ;
 
 extern int errno ;
 
-/* high level routines */
+/***** high level routines */
 /* message functions */
-uint32_t slurm_init_message_engine ( slurm_addr * slurm_address )
+
+/* 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
+ * slurm_fd		- file descriptor of the connection created
+ */
+slurm_fd slurm_init_message_engine ( slurm_addr * slurm_address )
 {
 	return _slurm_init_message_engine ( slurm_address ) ;
 }
 
+/* just calls close on an established message connection
+ * open_fd	- an open file descriptor
+ * uint32_t	- the return code
+ */
 uint32_t slurm_shutdown_message_engine ( slurm_fd open_fd ) 
 {
 	return _slurm_close ( open_fd ) ;
 }
 
-/* recv message functions */
+/***** recv message functions */
 /*
  * note that a memory is allocated for the returned message and must be freed at some point 
- * open_fd - file descriptor to receive message on
- * source_address - address of the source of the message
- * message - the message itself
+ * open_fd 		- file descriptor to receive message on
+ * source_address 	- address of the source of the message for now it is really just a sockaddr_in
+ * message 		- a slurm message struct
+ * uint32_t		- size of message received in bytes
  */
-uint32_t slurm_receive_message ( slurm_fd open_fd , slurm_addr * source_address , slurm_message_t * message ) 
+uint32_t slurm_receive_message ( slurm_fd open_fd , slurm_addr * source_address , slurm_message_t ** message ) 
 {
 	char buftemp[MAX_MESSAGE_BUFFER_SIZE] ;
 	char * buffer = buftemp ;
@@ -65,11 +76,19 @@ uint32_t slurm_receive_message ( slurm_fd open_fd , slurm_addr * source_address
 	new_message -> message_type = header . message_type ;
 	unpack_message ( & buffer , & unpack_len , new_message ) ;
 
-	message = new_message ;	
+	*message = new_message ;	
 	return receive_len ;
 }
 
-/* send message functions */
+/***** send message functions */
+/* sends a slurm_protocol message to the slurmctld based on location information retrieved from the slurmd.conf
+ * if unable to contant the primary slurmctld attempts will be made to contact the backup controller
+ * 
+ * open_fd	- file descriptor to send message on
+ * message_type	- type of message to be sent ( see slurm_protocol_defs.h for message types )
+ * message	- a slurm message struct
+ * uint32_t	- size of message sent in bytes
+ */
 uint32_t slurm_send_server_message ( slurm_fd open_fd , slurm_message_type_t message_type , slurm_message_t const * message )
 {
 	return SLURM_NOT_IMPLEMENTED ;	
@@ -105,7 +124,7 @@ uint32_t slurm_send_node_message ( slurm_fd open_fd , slurm_addr * destination_a
 	}
 	return pack_len ;
 }
-/* No overloading allowe 
+/* No overloading allowed
    uint32_t slurm_send_server_message ( slurm_fd open_fd , slurm_message_type_t message_type , char * buffer , size_t buf_len )
    {
    return SLURM_NOT_IMPLEMENTED ;	
@@ -134,18 +153,18 @@ uint32_t slurm_send_node_message ( slurm_fd open_fd , slurm_addr * destination_a
    }
  */
 
-/* stream functions */
-uint32_t slurm_listen_stream ( slurm_addr * slurm_address )
+/***** stream functions */
+slurm_fd slurm_listen_stream ( slurm_addr * slurm_address )
 {
 	return _slurm_listen_stream ( slurm_address ) ;
 }
 
-uint32_t slurm_accept_stream ( slurm_fd open_fd , slurm_addr * slurm_address )
+slurm_fd slurm_accept_stream ( slurm_fd open_fd , slurm_addr * slurm_address )
 {
 	return _slurm_accept_stream ( open_fd , slurm_address ) ;
 }
 
-uint32_t slurm_open_stream ( slurm_addr * slurm_address )
+slurm_fd slurm_open_stream ( slurm_addr * slurm_address )
 {
 	return _slurm_open_stream ( slurm_address ) ;
 }

src/common/slurm_protocol_api.h

@@ -7,16 +7,16 @@
 
 /* high level routines */
 /* message functions */
-uint32_t slurm_init_message_engine ( slurm_addr * slurm_address ) ;
-uint32_t slurm_receive_message ( slurm_fd open_fd , slurm_addr * source_address , slurm_message_t * message ) ; 
+slurm_fd slurm_init_message_engine ( slurm_addr * slurm_address ) ;
+uint32_t slurm_receive_message ( slurm_fd open_fd , slurm_addr * source_address , slurm_message_t ** message ) ; 
 uint32_t slurm_shutdown_message_engine ( slurm_fd open_fd ) ;
 
 /* send message functions */
 
 /* stream functions */
-uint32_t slurm_listen_stream ( slurm_addr * slurm_address ) ;
-uint32_t slurm_accept_stream ( slurm_fd open_fd , slurm_addr * slurm_address ) ;
-uint32_t slurm_open_stream ( slurm_addr * slurm_address )	;
+slurm_fd slurm_listen_stream ( slurm_addr * slurm_address ) ;
+slurm_fd slurm_accept_stream ( slurm_fd open_fd , slurm_addr * slurm_address ) ;
+slurm_fd slurm_open_stream ( slurm_addr * slurm_address )	;
 ssize_t slurm_write_stream ( slurm_fd open_fd , char * buffer , size_t size ) ;
 ssize_t slurm_read_stream ( slurm_fd open_fd , char * buffer , size_t size ) ;
 uint32_t slurm_close_stream ( slurm_fd open_fd ) ;
@@ -25,7 +25,7 @@ uint32_t slurm_close_stream ( slurm_fd open_fd ) ;
 
 /* Low level routines */
 /* message functions */
-/*
+/* junk
  * uint32_t slurm_message_send_server ( slurm_fd open_fd ,  slurm_message_type_t message_type , char * buffer , size_t buflen ) ;
  * uint32_t slurm_message_send_node( slurm_fd open_fd , slurm_addr slurm_address , slurm_message_type_t message_type , char * buffer , size_t buflen) ;
  */

src/common/slurm_protocol_common.h

 #ifndef _SLURM_PROTOCOL_COMMON_H
 #define _SLURM_PROTOCOL_COMMON_H
+
 /* LINUX SPECIFIC */
+/* this is the slurm equivalent of the operating system file descriptor, which in linux is just an int */
 typedef uint32_t slurm_fd ;
+/* this is the slurm equivalent of the BSD sockets sockaddr */
 typedef struct sockaddr_in slurm_addr ;
+
+
+/* SLURM datatypes */
+/* this is a custom data type to describe the slurm message type type that is placed in the slurm protocol header
+ * while just an short now, it may change in the future */
 typedef uint16_t slurm_message_type_t ;
 
 #endif

src/common/slurm_protocol_interface.h

@@ -19,26 +19,28 @@
 #include "slurm_protocol_common.h"
 
 
-/***********\
- **  Notes  **
- \***********/
-
-/*  When a memory allocation request fails, the list returns out_of_memory().
- *  By default, this is a macro definition that returns NULL; this macro may
- *  be redefined to invoke another routine instead.  Furthermore, if WITH_OOMF
- *  is defined, this macro will not be defined and the list will expect an
- *  external Out-Of-Memory Function to be defined.
- */
-
 
 /****************\
  **  Data Types  **
  \****************/
 
 
+
+/*******************************\
+ **  Must Have Functions  **
+ \*******************************/
+/* The must have funtions are required to implement a low level plugin for the slurm protocol
+ * the genereal purpose functions just wrap standard socket calls, so if the underlying layer 
+ * implements a socket like interface, it can be used as a low level transport plugin with slurm
+ *
+ * the _slurm_recv and _slurm_send functions are also needed
+ */
+
+
 typedef enum slurm_socket_type { SLURM_MESSAGE , SLURM_STREAM } slurm_socket_type_t;
 
 /* high level interface */
+extern int _slurm_create_socket (slurm_socket_type_t type) __THROW ;
 /* message functions */
 uint32_t _slurm_init_message_engine ( slurm_addr * slurm_address ) ;
 ssize_t _slurm_message_recvfrom ( slurm_fd open_fd, char *buffer , size_t size , uint32_t flags, slurm_addr * slurm_address ) ;
@@ -59,7 +61,6 @@ uint32_t _slurm_open_stream ( slurm_addr * slurm_address ) ;
  *       Returns a file descriptor for the new socket, or -1 for errors.  */
 extern int _slurm_socket (int __domain, int __type, int __protocol) __THROW ;
 
-extern int _slurm_create_socket (slurm_socket_type_t type) __THROW ;
 
 
 /* Create two new sockets, of type TYPE in domain DOMAIN and using
@@ -147,7 +148,8 @@ extern int _slurm_close (int __fd ) __THROW;
 extern int _slurm_select(int n, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout);
 
 extern int _slurm_pselect(int n, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, const struct timespec *timeout, sigset_t * sigmask);
-/*
+
+/* not yet implemented
 _slurm_FD_CLR(int fd, fd_set *set);
 _slurm_FD_ISSET(int fd, fd_set *set);
 _slurm_FD_SET(int fd, fd_set *set);

src/common/slurm_protocol_util.c

@@ -5,6 +5,7 @@
 
 extern int debug ;
 
+/* checks to see that the specified header was sent from a node running the same version of the protocol as the current node */
 uint32_t check_header_version( header_t * header)
 {
 	if ( header -> version != SLURM_PROTOCOL_VERSION )
@@ -18,6 +19,7 @@ uint32_t check_header_version( header_t * header)
 	return SLURM_PROTOCOL_SUCCESS ;
 }
 
+/* simple function to create a header, always insuring that an accurate version string is inserted */
 void init_header ( header_t * header , slurm_message_type_t message_type , uint16_t flags )
 {
 	header -> version = SLURM_PROTOCOL_VERSION ;