Minimalist documentation for the headers in src/core/

src/core/debug.h

@@ -24,9 +24,13 @@
 #include <common/config.h>
 #include <core/workers.h>
 
+/* Create a file that will contain StarPU's log */
 void _starpu_open_debug_logfile(void);
+
+/* Close StarPU's log file */
 void _starpu_close_debug_logfile(void);
 
+/* Write into StarPU's log file */
 void _starpu_print_to_logfile(const char *format, ...);
 
 #endif // __DEBUG_H__

src/core/errorcheck.h

@@ -19,6 +19,7 @@
 
 #include <starpu.h>
 
+/* This type describes in which state a worker may be. */
 typedef enum {
 	/* invalid status (for instance if we request the status of some thread
 	 * that is not controlled by StarPU */
@@ -35,7 +36,12 @@ typedef enum {
 	STATUS_SLEEPING
 } starpu_worker_status;
 
+/* Specify what the local worker is currently doing (eg. executing a callback).
+ * This permits to detect if this is legal to do a blocking call for instance.
+ * */
 void _starpu_set_local_worker_status(starpu_worker_status st);
+
+/* Indicate what type of operation the worker is currently doing. */
 starpu_worker_status _starpu_get_local_worker_status(void);
 
 /* It is forbidden to do blocking calls during some operations such as callback

src/core/jobs.c

@@ -363,8 +363,10 @@ int _starpu_push_local_task(struct starpu_worker_s *worker, struct starpu_job_s
 	return 0;
 }
 
-const char *_starpu_get_model_name(starpu_job_t j) {
-	if (!j) return NULL;
+const char *_starpu_get_model_name(starpu_job_t j)
+{
+	if (!j)
+		return NULL;
 
 	struct starpu_task *task = j->task;
         if (task && task->cl

src/core/jobs.h

@@ -51,39 +51,72 @@ typedef void (*callback)(void *);
 #define STARPU_GORDON_MAY_PERFORM(j)	((j)->task->cl->where & STARPU_GORDON)
 #define STARPU_OPENCL_MAY_PERFORM(j)	((j)->task->cl->where & STARPU_OPENCL)
 
-/* a job is the internal representation of a task */
+/* A job is the internal representation of a task. */
 LIST_TYPE(starpu_job,
+	/* The task associated to that job */
 	struct starpu_task *task;
 
+	/* These synchronization structures are used to wait for the job to be
+	 * available or terminated for instance. */
 	pthread_mutex_t sync_mutex;
 	pthread_cond_t sync_cond;
 
+	/* To avoid deadlocks, we reorder the different buffers accessed to by
+	 * the task so that we always grab the rw-lock associated to the
+	 * handles in the same order. */
 	struct starpu_buffer_descr_t ordered_buffers[STARPU_NMAXBUFS];
 	
+	/* In case the task accesses a piece of data in SCRATCH mode, we create
+	 * a memchunk specifically for that purpose when the task is submitted.
+	 * It is put back into the memchunk cache when the task is finished. */
 	starpu_mem_chunk_t scratch_memchunks[STARPU_NMAXBUFS];
 
+	/* If a tag is associated to the job, this points to the internal data
+	 * structure that describes the tag status. */
 	struct starpu_tag_s *tag;
+
+	/* Maintain a list of all the completion groups that depend on the job.
+	 * */
 	struct starpu_cg_list_s job_successors;
 
+	/* The value of the footprint that identifies the job may be stored in
+	 * this structure. */
 	unsigned footprint_is_computed;
 	uint32_t footprint;
 
+	/* Indicates whether the task associated to that job has already been
+	 * submitted to StarPU or not (using starpu_task_submit). */
 	unsigned submitted;
+
+	/* Indicates whether the task associated to this job is terminated or
+	 * not. */
 	unsigned terminated;
 
+	/* Should that task appear in the debug tools ? (eg. the DAG generated
+	 * with dot) */
         unsigned exclude_from_dag;
 
+	/* Each job is attributed a unique id. */
 	unsigned long job_id;
+
 #ifdef STARPU_USE_FXT
+	/* A symbol name may be associated to the job directly for debug
+	 * purposes (for instance if the codelet is NULL). */
         const char *model_name;
 #endif
 	struct bound_task *bound_task;
 );
 
+/* Create an internal starpu_job_t structure to encapsulate the task. */
 starpu_job_t __attribute__((malloc)) _starpu_job_create(struct starpu_task *task);
+
+/* Destroy the data structure associated to the job structure */
 void _starpu_job_destroy(starpu_job_t j);
+
+/* Wait for the termination of the job */
 void _starpu_wait_job(starpu_job_t j);
 
+/* Specify that the task should not appear in the DAG generated by debug tools. */
 void _starpu_exclude_task_from_dag(struct starpu_task *task);
 
 /* try to submit job j, enqueue it if it's not schedulable yet */
@@ -91,14 +124,22 @@ unsigned _starpu_enforce_deps_and_schedule(starpu_job_t j, unsigned job_is_alrea
 unsigned _starpu_enforce_deps_starting_from_task(starpu_job_t j, unsigned job_is_already_locked);
 
 
-//#warning this must not be exported anymore ... 
-//starpu_job_t _starpu_job_create(struct starpu_task *task);
+/* This function must be called after the execution of a job, this triggers all
+ * job's dependencies and perform the callback function if any. */
 void _starpu_handle_job_termination(starpu_job_t j, unsigned job_is_already_locked);
+
+/* Get the sum of the size of the data accessed by the job. */
 size_t _starpu_job_get_data_size(starpu_job_t j);
 
+/* Get a task from the local pool of tasks that were explicitly attributed to
+ * that worker. */
 starpu_job_t _starpu_pop_local_task(struct starpu_worker_s *worker);
+
+/* Put a task into the pool of tasks that are explicitly attributed to the
+ * specified worker. */
 int _starpu_push_local_task(struct starpu_worker_s *worker, starpu_job_t j);
 
+/* Returns the symbol associated to that job if any. */
 const char *_starpu_get_model_name(starpu_job_t j);
 
 #endif // __JOBS_H__

src/core/task.h

@@ -34,6 +34,9 @@ void _starpu_set_current_task(struct starpu_task *task);
 /* NB the second argument makes it possible to count regenerable tasks only
  * once. */
 int _starpu_submit_job(starpu_job_t j, unsigned do_not_increment_nsubmitted);
+
+/* Returns the job structure (which is the internal data structure associated
+ * to a task). */
 starpu_job_t _starpu_get_job_associated_to_task(struct starpu_task *task);
 
 #endif // __CORE_TASK_H__

src/core/topology.h

@@ -25,13 +25,18 @@
 /* TODO actually move this struct into this header */
 struct starpu_machine_config_s;
 
+/* Detect the number of memory nodes and where to bind the different workers. */
 int _starpu_build_topology(struct starpu_machine_config_s *config);
 
+/* Destroy all resources used to store the topology of the machine. */
 void _starpu_destroy_topology(struct starpu_machine_config_s *config);
 
 /* returns the number of physical cpus */
 unsigned _starpu_topology_get_nhwcpu(struct starpu_machine_config_s *config);
 
+/* Bind the current thread on the CPU logically identified by "cpuid". The
+ * logical ordering of the processors is either that of hwloc (if available),
+ * or the ordering exposed by the OS. */
 void _starpu_bind_thread_on_cpu(struct starpu_machine_config_s *config, unsigned cpuid);
 
 #endif // __TOPOLOGY_H__

src/core/workers.h

@@ -151,11 +151,21 @@ unsigned _starpu_worker_can_block(unsigned memnode);
  * */
 void _starpu_block_worker(int workerid, pthread_cond_t *cond, pthread_mutex_t *mutex);
 
+/* The starpu_worker_s structure describes all the state of a StarPU worker.
+ * This function sets the pthread key which stores a pointer to this structure.
+ * */
 void _starpu_set_local_worker_key(struct starpu_worker_s *worker);
+
+/* Returns the starpu_worker_s structure that describes the state of the
+ * current worker. */
 struct starpu_worker_s *_starpu_get_local_worker_key(void);
 
+/* Returns the starpu_worker_s structure that describes the state of the
+ * specified worker. */
 struct starpu_worker_s *_starpu_get_worker_struct(unsigned id);
 
+/* Returns the structure that describes the overall machine configuration (eg.
+ * all workers and topology). */
 struct starpu_machine_config_s *_starpu_get_machine_config(void);
 
 /* Retrieve the status which indicates what the worker is currently doing. */