[Swift-commit] cog r3948

[swift at ci.uchicago.edu]

------------------------------------------------------------------------
r3948 | timgarmstrong | 2014-06-23 09:17:48 -0500 (Mon, 23 Jun 2014) | 1 line

Little documentation and a note about object lifetime for settings.
------------------------------------------------------------------------
Index: modules/provider-coaster-c-client/src/ServiceConfigurationCommand.h
===================================================================
--- modules/provider-coaster-c-client/src/ServiceConfigurationCommand.h	(revision 3947)
+++ modules/provider-coaster-c-client/src/ServiceConfigurationCommand.h	(working copy)
@@ -14,6 +14,7 @@
 		Settings* settings;
 	public:
 		static string NAME;
+                // TODO: how long does this hold a reference to settings?
 		ServiceConfigurationCommand(Settings& s);
 		virtual void send(CoasterChannel* channel, CommandCallback* cb);
 	private:
Index: modules/provider-coaster-c-client/src/CoasterClient.h
===================================================================
--- modules/provider-coaster-c-client/src/CoasterClient.h	(revision 3947)
+++ modules/provider-coaster-c-client/src/CoasterClient.h	(working copy)
@@ -60,7 +60,8 @@
 		virtual ~CoasterClient();
 		void start();
 		void stop();
-
+                
+                // TODO: how long does this hold a reference to settings?
 		void setOptions(Settings& settings);
 
 		/*
Index: modules/provider-coaster-c-client/src/coasters.h
===================================================================
--- modules/provider-coaster-c-client/src/coasters.h	(revision 3947)
+++ modules/provider-coaster-c-client/src/coasters.h	(working copy)
@@ -20,7 +20,9 @@
  * Created: Jun 18, 2014
  *    Author: Tim Armstrong
  *
- * Pure C interface for Coasters
+ * Pure C interface for Coasters.  This aims to expose a subset of the
+ * C++ API's functionality that is sufficient to support all common use
+ * cases for submitting jobs through Coasters.
  */
 
 #ifndef COASTERS_H_
@@ -56,7 +58,6 @@
 } coaster_rc;
 
 // Set appropriate macro to specify that we shouldn't throw exceptions
-// Only used in this header: undefine later
 #ifdef __cplusplus
 #define COASTERS_THROWS_NOTHING throw()
 #else
@@ -75,7 +76,10 @@
                     coaster_client **client) COASTERS_THROWS_NOTHING;
 
 /*
- * Stop coasters client and free memory.
+ * Stop coasters client and free all memory.
+ *
+ * After calling this the client is invalid and should not be used as
+ * an argument to any more Coaster C API function calls.
  */
 coaster_rc
 coaster_client_stop(coaster_client *client) COASTERS_THROWS_NOTHING;
@@ -90,6 +94,13 @@
                     COASTERS_THROWS_NOTHING;
 
 /*
+ * Free memory associated with coasters settings
+ */
+void
+coaster_settings_free(coaster_settings *settings)
+                                COASTERS_THROWS_NOTHING;
+
+/*
  * Parse settings from string.
  *
  * str[_len]: String with key/value settings and length of string.
@@ -130,12 +141,10 @@
                       const char ***keys, size_t **key_lens, int *count)
                                 COASTERS_THROWS_NOTHING;
 
-void
-coaster_settings_free(coaster_settings *settings)
-                                COASTERS_THROWS_NOTHING;
-
 /*
  * Apply settings to started coasters client.
+ * TODO: currently it isn't safe to free settings until client is shut
+ *       down
  */
 coaster_rc
 coaster_apply_settings(coaster_client *client,
@@ -165,7 +174,7 @@
 coaster_job_free(coaster_job *job) COASTERS_THROWS_NOTHING;
 
 /*
- * Set input and output streams redirections.
+ * Set input and output stream redirections.
  * If set to NULL, don't modify.
  */
 coaster_rc
@@ -214,13 +223,14 @@
 // TODO: functions for setting stageins, stageouts
 
 /*
- * Get local job ID.
+ * Get local job ID.  The job ID is a locally unique identifier for
+ * a coasters job that is assigned when the job is created.
  */
 job_id_t 
 coaster_job_get_id(coaster_job *job) COASTERS_THROWS_NOTHING;
 
 /*
- * Get status of job.
+ * Get status of a submitted job.
  * Return COASTER_ERROR_INVALID if job is invalid or has no status.
  */
 coaster_rc
@@ -239,7 +249,7 @@
                 COASTERS_THROWS_NOTHING;
 
 /*
- * Submit a coasters job.
+ * Submit a coasters job through a coasters client.
  * A job can only be submitted once!
  */
 coaster_rc