General code cleanup, add disclaimer, function descriptions.

src/common/slurm_protocol_util.c

@@ -29,14 +29,17 @@
 #include <string.h>
 #include <assert.h>
 
-#include <src/common/slurm_protocol_defs.h>
-#include <src/common/slurm_protocol_api.h>
-#include <src/common/slurm_protocol_common.h>
-#include <src/common/slurm_protocol_util.h>
-#include <src/common/log.h>
-#include <src/common/xmalloc.h>
-
-/* checks to see that the specified header was sent from a node running the same version of the protocol as the current node */
+#include "src/common/slurm_protocol_api.h"
+#include "src/common/slurm_protocol_util.h"
+#include "src/common/log.h"
+#include "src/common/xmalloc.h"
+
+/* 
+ * check_header_version checks to see that the specified header was sent 
+ * from a node running the same version of the protocol as the current node 
+ * IN header - the message header received
+ * RET - SLURM error code
+ */
 uint32_t check_header_version(header_t * header)
 {
 	if (header->version != SLURM_PROTOCOL_VERSION) {
@@ -46,7 +49,13 @@ 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 */
+/*
+ * init_header - simple function to create a header, always insuring that 
+ * an accurate version string is inserted
+ * OUT header - the message header to be send
+ * IN msg_type - type of message to be send
+ * IN flags - message flags to be send
+ */
 void init_header(header_t * header, slurm_msg_type_t msg_type,
 		 uint16_t flags)
 {
@@ -55,6 +64,12 @@ void init_header(header_t * header, slurm_msg_type_t msg_type,
 	header->msg_type = msg_type;
 }
 
+/*
+ * update_header - update a message header with the credential and message len
+ * OUT header - the message header to update
+ * IN cred_length - credential length
+ * IN msg_length - length of message to be send 
+ */
 void update_header(header_t * header, uint32_t cred_length,
 		   uint32_t msg_length)
 {
@@ -62,7 +77,13 @@ void update_header(header_t * header, uint32_t cred_length,
 	header->body_length = msg_length;
 }
 
-/* checks to see that the specified header was sent from a node running the same version of the protocol as the current node */
+/*
+ * check_io_stream_header_version checks to see that the specified header 
+ *	was sent from a node running the same version of the protocol as 
+ *	the current node
+ * IN header - the message recevied
+ * RET - SLURM error code
+ */
 uint32_t check_io_stream_header_version(slurm_io_stream_header_t * header)
 {
 	if (header->version != SLURM_PROTOCOL_VERSION) {
@@ -73,7 +94,14 @@ uint32_t check_io_stream_header_version(slurm_io_stream_header_t * header)
 	return SLURM_PROTOCOL_SUCCESS;
 }
 
-/* simple function to create a header, always insuring that an accurate version string is inserted */
+/*
+ * init_io_stream_header - simple function to create a header, always 
+ *	insuring that an accurate version string is inserted
+ * OUT header - the message header to be sent
+ * IN key - authentication signature
+ * IN task_id - message's task_id
+ * IN type - message type
+ */
 void init_io_stream_header(slurm_io_stream_header_t * header, char *key,
 			   uint32_t task_id, uint16_t type)
 {
@@ -84,7 +112,14 @@ void init_io_stream_header(slurm_io_stream_header_t * header, char *key,
 	header->type = type;
 }
 
-int read_io_stream_header(slurm_io_stream_header_t * header, int fd)
+/*
+ * read an i/o stream header from the supplied slurm stream
+ *	data is copied in a block
+ * IN fd - the file descriptor to read from
+ * OUT header - the header read
+ * RET number of bytes read
+ */
+int read_io_stream_header(slurm_io_stream_header_t * header, slurm_fd fd)
 {
 	char *data;
 	int  buf_size, rsize;
@@ -103,7 +138,14 @@ int read_io_stream_header(slurm_io_stream_header_t * header, int fd)
 	return rsize;
 }
 
-int write_io_stream_header(slurm_io_stream_header_t * header, int fd)
+/*
+ * write an i/o stream header to the supplied slurm stream
+ *	data is copied in a block
+ * IN fd - the file descriptor to read from
+ * IN header - the header read
+ * RET number of bytes written
+ */
+int write_io_stream_header(slurm_io_stream_header_t * header, slurm_fd fd)
 {
 	int  buf_size, wsize;
 	Buf my_buf;
@@ -111,12 +153,20 @@ int write_io_stream_header(slurm_io_stream_header_t * header, int fd)
 	buf_size = sizeof(slurm_io_stream_header_t);
 	my_buf = init_buf(buf_size);
 	pack_io_stream_header(header, my_buf);
-	wsize = slurm_write_stream(fd, get_buf_data(my_buf), get_buf_offset(my_buf));
+	wsize = slurm_write_stream(fd, get_buf_data(my_buf), 
+	                           get_buf_offset(my_buf));
 	free_buf(my_buf);
 	return wsize;
 }
 
-int read_io_stream_header2(slurm_io_stream_header_t * header, int fd)
+/*
+ * read an i/o stream header from the supplied slurm stream
+ *	data is unpacked field by field
+ * IN fd - the file descriptor to read from
+ * OUT header - the header read
+ * RET number of bytes read
+ */
+int read_io_stream_header2(slurm_io_stream_header_t * header, slurm_fd fd)
 {
 	int rsize;
 
@@ -126,7 +176,8 @@ int read_io_stream_header2(slurm_io_stream_header_t * header, int fd)
 		return rsize;
 	header->version = ntohs(header->version);
 
-	rsize = slurm_read_stream(fd, (char *) &header->key, sizeof(header->key));
+	rsize = slurm_read_stream(fd, (char *) &header->key,
+	                          sizeof(header->key));
 	if (rsize != sizeof(header->key)) 
 		return rsize;
 
@@ -136,7 +187,8 @@ int read_io_stream_header2(slurm_io_stream_header_t * header, int fd)
 		return rsize;
 	header->task_id = ntohl(header->task_id);
 
-	rsize = slurm_read_stream(fd, (char *) &header->type, sizeof(header->type));
+	rsize = slurm_read_stream(fd, (char *) &header->type, 
+	                          sizeof(header->type));
 	if (rsize != sizeof(header->type))
 		return rsize;
 	header->type = ntohs(header->type);
@@ -144,7 +196,14 @@ int read_io_stream_header2(slurm_io_stream_header_t * header, int fd)
 	return SLURM_SUCCESS;
 }
 
-int write_io_stream_header2(slurm_io_stream_header_t * header, int fd)
+/*
+ * write an i/o stream header to the supplied slurm stream
+ *	data is packed field by field
+ * IN fd - the file descriptor to read from
+ * IN header - the header read
+ * RET number of bytes written
+ */
+int write_io_stream_header2(slurm_io_stream_header_t * header, slurm_fd fd)
 {
 	int write_size;
 	slurm_io_stream_header_t header2 = *header;
@@ -183,8 +242,8 @@ int write_io_stream_header2(slurm_io_stream_header_t * header, int fd)
 	return SLURM_SUCCESS;
 }
 
-void slurm_print_job_credential(FILE * stream,
-				slurm_job_credential_t * credential)
+/* log the supplied slurm credential as debug3() level */
+void slurm_print_job_credential(slurm_job_credential_t * credential)
 {
 	debug3("credential.job_id: %i", credential->job_id);
 	debug3("credential.user_id: %i", credential->user_id);
@@ -194,13 +253,15 @@ void slurm_print_job_credential(FILE * stream,
 	debug3("credential.signature: %#x", credential->signature);
 }
 
+/* log the supplied slurm task launch message as debug3() level */
 void slurm_print_launch_task_msg(launch_tasks_request_msg_t * msg)
 {
 	int i;
+
 	debug3("job_id: %i", msg->job_id);
 	debug3("job_step_id: %i", msg->job_step_id);
 	debug3("uid: %i", msg->uid);
-	slurm_print_job_credential(stderr, msg->credential);
+	slurm_print_job_credential(msg->credential);
 	debug3("tasks_to_launch: %i", msg->tasks_to_launch);
 	debug3("envc: %i", msg->envc);
 	for (i = 0; i < msg->envc; i++) {

src/common/slurm_protocol_util.h

+/*****************************************************************************\
+ *  slurm_protocol_util.h - communication infrastructure functions
+ *****************************************************************************
+ *  Copyright (C) 2002 The Regents of the University of California.
+ *  Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER).
+ *  Written by Kevin Tew <tew1@llnl.gov> et. al.
+ *  UCRL-CODE-2002-040.
+ *  
+ *  This file is part of SLURM, a resource management program.
+ *  For details, see <http://www.llnl.gov/linux/slurm/>.
+ *  
+ *  SLURM is free software; you can redistribute it and/or modify it under
+ *  the terms of the GNU General Public License as published by the Free
+ *  Software Foundation; either version 2 of the License, or (at your option)
+ *  any later version.
+ *  
+ *  SLURM is distributed in the hope that it will be useful, but WITHOUT ANY
+ *  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ *  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+ *  details.
+ *  
+ *  You should have received a copy of the GNU General Public License along
+ *  with SLURM; if not, write to the Free Software Foundation, Inc.,
+ *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.
+\*****************************************************************************/
+
 #ifndef _SLURM_PROTOCOL_UTIL_H
 #define _SLURM_PROTOCOL_UTIL_H
 
 #if HAVE_CONFIG_H
-#  include <config.h>
+#  include "config.h"
 #  if HAVE_INTTYPES_H
 #    include <inttypes.h>
 #  else
@@ -16,25 +42,99 @@
 
 #include <stdio.h>
 
-#include <src/common/slurm_protocol_defs.h>
-#include <src/common/slurm_protocol_pack.h>
-#include <src/common/slurm_protocol_common.h>
-
-/* slurm protocol header functions */
-uint32_t check_header_version(header_t * header);
-void init_header(header_t * header, slurm_msg_type_t msg_type,
-		 uint16_t flags);
-
-/* io stream header functions */
-uint32_t check_io_stream_header_version(slurm_io_stream_header_t * header);
-void init_io_stream_header(slurm_io_stream_header_t * header, char *key,
-			   uint32_t task_id, uint16_t type);
-void update_header(header_t * header, uint32_t cred_length,
-		   uint32_t msg_length);
-
-/* debug print methods */
-void slurm_print_job_credential(FILE * stream,
-				slurm_job_credential_t * credential);
-void slurm_print_launch_task_msg(launch_tasks_request_msg_t * msg);
+#include "src/common/slurm_protocol_defs.h"
+#include "src/common/slurm_protocol_pack.h"
+#include "src/common/slurm_protocol_common.h"
+
+/* 
+ * check_header_version checks to see that the specified header was sent 
+ * from a node running the same version of the protocol as the current node 
+ * IN header - the message header received
+ * RET - SLURM error code
+ */
+extern uint32_t check_header_version(header_t * header);
+
+/*
+ * init_header - simple function to create a header, always insuring that 
+ * an accurate version string is inserted
+ * OUT header - the message header to be send
+ * IN msg_type - type of message to be send
+ * IN flags - message flags to be send
+ */
+extern void 
+init_header(header_t * header, slurm_msg_type_t msg_type, uint16_t flags);
+
+/*
+ * check_io_stream_header_version checks to see that the specified header 
+ *	was sent from a node running the same version of the protocol as 
+ *	the current node
+ * IN header - the message recevied
+ * RET - SLURM error code
+ */
+extern uint32_t 
+check_io_stream_header_version(slurm_io_stream_header_t * header);
+
+/*
+ * init_io_stream_header - simple function to create a header, always 
+ *	insuring that an accurate version string is inserted
+ * OUT header - the message header to be sent
+ * IN key - authentication signature
+ * IN task_id - message's task_id
+ * IN type - message type
+ */
+extern void 
+init_io_stream_header(slurm_io_stream_header_t * header, char *key,
+                      uint32_t task_id, uint16_t type);
+
+/*
+ * update_header - update a message header with the credential and message len
+ * OUT header - the message header to update
+ * IN cred_length - credential length
+ * IN msg_length - length of message to be send 
+ */
+extern void 
+update_header(header_t * header, uint32_t cred_length, uint32_t msg_length);
+
+/*
+ * read an i/o stream header from the supplied slurm stream
+ *	data is copied in a block
+ * IN fd - the file descriptor to read from
+ * OUT header - the header read
+ * RET number of bytes read
+ */
+extern int read_io_stream_header(slurm_io_stream_header_t * header, slurm_fd fd);
+
+/*
+ * read an i/o stream header from the supplied slurm stream
+ *	data is unpacked field by field
+ * IN fd - the file descriptor to read from
+ * OUT header - the header read
+ * RET number of bytes read
+ */
+extern int read_io_stream_header2(slurm_io_stream_header_t * header, slurm_fd fd);
+
+/*
+ * write an i/o stream header to the supplied slurm stream
+ *	data is copied in a block
+ * IN fd - the file descriptor to read from
+ * IN header - the header read
+ * RET number of bytes written
+ */
+extern int write_io_stream_header(slurm_io_stream_header_t * header, slurm_fd fd);
+
+/* log the supplied slurm credential as debug3() level */
+extern void slurm_print_job_credential(slurm_job_credential_t * credential);
+
+/*
+ * write an i/o stream header to the supplied slurm stream
+ *	data is packed field by field
+ * IN fd - the file descriptor to read from
+ * IN header - the header read
+ * RET number of bytes written
+ */
+extern int write_io_stream_header2(slurm_io_stream_header_t * header, slurm_fd fd);
+
+/* log the supplied slurm task launch message as debug3() level */
+extern void slurm_print_launch_task_msg(launch_tasks_request_msg_t * msg);
 
 #endif /* !_SLURM_PROTOCOL_UTIL_H */