Adding doxygen comments for Charm Scheduler routines.
authorIsaac Dooley <idooley2@illinois.edu>
Sat, 12 Sep 2009 19:49:46 +0000 (19:49 +0000)
committerIsaac Dooley <idooley2@illinois.edu>
Sat, 12 Sep 2009 19:49:46 +0000 (19:49 +0000)
src/conv-core/convcore.c
src/conv-core/converse.h
src/conv-core/queueing.c
src/conv-core/queueing.h

index 7bb59f39e7549b3efd0391d1cb57786b1ea1b473..ab8452b4bc96bdae430399865a89f036aca0267d 100644 (file)
@@ -4,43 +4,42 @@
  * $Date$
  * $Revision$
  *****************************************************************************/
-/** @defgroup Converse
- * \brief Converse--a parallel portability layer.
-
- * Converse is the lowest level inside the Charm++ hierarchy. It stands on top
- * of the machine layer, and it provides all the common functionality across
- * platforms.
-
- * One converse program is running on every processor (or node in the smp
- * version). it manages the message transmission, and the memory allocation.
- * Charm++, which is on top of Converse, uses its functionality for
- * interprocess *communication.
-
- * In order to maintain multiple independent objects inside a single user space
- * program, it uses a personalized version of threads, which can be executed,
- * suspended, and migrated across processors.
-
- * It provides a scheduler for message delivery: methods can be registered to
- * the scheduler, and then messages allocated through CmiAlloc can be sent to
- * the correspondent method in a remote processor. This is done through the
- * converse header (which has few common fields, but is architecture dependent).
-*/
+/** 
+  @defgroup Converse
+  \brief Converse--a parallel portability layer.
+
+  Converse is the lowest level inside the Charm++ hierarchy. It stands on top
+  of the machine layer, and it provides all the common functionality across
+  platforms.
+
+  One converse program is running on every processor (or node in the smp
+  version). it manages the message transmission, and the memory allocation.
+  Charm++, which is on top of Converse, uses its functionality for
+  interprocess *communication.
+
+  In order to maintain multiple independent objects inside a single user space
+  program, it uses a personalized version of threads, which can be executed,
+  suspended, and migrated across processors.
+
+  It provides a scheduler for message delivery: methods can be registered to
+  the scheduler, and then messages allocated through CmiAlloc can be sent to
+  the correspondent method in a remote processor. This is done through the
+  converse header (which has few common fields, but is architecture dependent).
+
+  @defgroup Scheduler 
+  \brief The portion of Converse responsible for scheduling the execution of 
+  incoming messages.
+
+  @file
+  converse main core
+  @ingroup Converse
+  @ingroup Scheduler
+  @addtogroup Converse
+  @{
 
-/** @defgroup Scheduler 
-    \brief The portion of Converse responsible for scheduling the execution of incoming messages
 */
 
-/** @file
- * converse main core
- * @ingroup Converse
- * @ingroup Scheduler
- */
-
-/**
- * @addtogroup Converse
- * @{
- */
-
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
index 0e49076588e3215ec6dd530183cb71d608ab41c3..be3c59f8783ed372a8b7411e71b47ad99d946709 100644 (file)
@@ -6,7 +6,8 @@
  *****************************************************************************/
 
 /**
-  Main Converse header file.  Everything in Converse is 
+  @file
+  @brief Main Converse header file.  Everything in Converse is 
   either declared here directly, or else included from here.
 
   Routine names in Converse include a short prefix starting with "C".
@@ -29,6 +30,9 @@
   - Ctv, Converse thread-private variable.  One copy per Converse thread. 
   - Csv, Converse node-shared variable.  Global variables 
      shared by all processors of a node (beware of thread safety!)
+
+  @addtogroup CharmScheduler
+
 */
 #ifndef CONVERSE_H
 #define CONVERSE_H
@@ -1097,8 +1101,10 @@ int    CmiDeliverMsgs(int maxmsgs);
 void   CmiDeliverSpecificMsg(int handler);
 void   CmiHandleMessage(void *msg);
 
-/******** CQS: THE QUEUEING SYSTEM ********/
-
+/******** CQS: THE QUEUEING SYSTEM ********
+ * @addtogroup CharmScheduler
+ * @{ 
+ */
 #define CQS_QUEUEING_FIFO 2
 #define CQS_QUEUEING_LIFO 3
 #define CQS_QUEUEING_IFIFO 4
@@ -1107,6 +1113,8 @@ void   CmiHandleMessage(void *msg);
 #define CQS_QUEUEING_BLIFO 7
 #define CQS_QUEUEING_LFIFO 8
 #define CQS_QUEUEING_LLIFO 9
+/** @} */
+
 
 /****** Isomalloc: Migratable Memory Allocation ********/
 /*Simple block-by-block interface:*/
index 0756a963c690d3e838071ef9fac34c2ec6a4bbd9..de062edc6ba7bb6adfc8faf8f00a26b73761ac21 100644 (file)
@@ -9,6 +9,29 @@
 #include <string.h>
 #include "queueing.h"
 
+/** @defgroup CharmScheduler 
+    \brief The portion of Charm++ responsible for scheduling the execution 
+    of Charm++ entry methods
+
+    CqsEnqueueGeneral() is the main function that is responsible for enqueueing 
+    messages. It will store the messages in one of three queues based on the 
+    specified priorities or strategies.
+
+    The charm++ messages are only scheduled after the converse message queues
+    have been emptied. After that, a message is pulled from the Charm++ queue
+    through a call to CqsDequeue().
+
+    The Charm++ message queue is really three queues, one for positive 
+    priorities, one for zero priorities, and one for negative priorities.
+    The positive and negative priorty queues are actually heaps.
+
+
+    @addtogroup CharmScheduler
+    @{
+*/
+
+
+/** Initialize a deq */
 static void CqsDeqInit(d)
 deq d;
 {
@@ -18,6 +41,7 @@ deq d;
   d->tail = d->space;
 }
 
+/** Double the size of a deq */
 static void CqsDeqExpand(d)
 deq d;
 {
@@ -36,6 +60,7 @@ deq d;
   if (ovec != d->space) CmiFree(ovec);
 }
 
+/** Insert a data pointer at the tail of a deq */
 void CqsDeqEnqueueFifo(d, data)
 deq d; void *data;
 {
@@ -47,6 +72,7 @@ deq d; void *data;
   if (tail == d->head) CqsDeqExpand(d);
 }
 
+/** Insert a data pointer at the head of a deq */
 void CqsDeqEnqueueLifo(d, data)
 deq d; void *data;
 {
@@ -58,6 +84,7 @@ deq d; void *data;
   if (head == d->tail) CqsDeqExpand(d);
 }
 
+/** Remove a data pointer from the head of a deq */
 void *CqsDeqDequeue(d)
 deq d;
 {
@@ -74,6 +101,7 @@ deq d;
   return data;
 }
 
+/** Initialize a Priority Queue */
 static void CqsPrioqInit(pq)
 prioq pq;
 {
@@ -90,6 +118,7 @@ prioq pq;
 #if CMK_C_INLINE
 inline
 #endif
+/** Double the size of a Priority Queue's heap */
 static void CqsPrioqExpand(prioq pq)
 {
   int oldsize = pq->heapsize;
@@ -102,6 +131,7 @@ static void CqsPrioqExpand(prioq pq)
   CmiFree(oheap);
 }
 #ifndef FASTQ
+/** Double the size of a Priority Queue's hash table */
 void CqsPrioqRehash(pq)
      prioq pq;
 {
@@ -139,16 +169,13 @@ void CqsPrioqRehash(pq)
   CmiFree(ohashtab);
 }
 #endif
-/*
- * This routine compares priorities. It returns:
- * 
- * 1 if prio1 > prio2
- * ? if prio1 == prio2
- * 0 if prio1 < prio2
- *
- * where prios are treated as unsigned
- */
 
+/**
+ * Compare two priorities (treated as unsigned).
+ * @return 1 if prio1 > prio2
+ * @return ? if prio1 == prio2
+ * @return 0 if prio1 < prio2
+ */
 int CqsPrioGT(prio1, prio2)
 prio prio1;
 prio prio2;
@@ -187,6 +214,7 @@ prio prio2;
   }
 }
 
+/** Find or create a bucket in the hash table for the specified priority. */
 deq CqsPrioqGetDeq(pq, priobits, priodata)
 prioq pq;
 unsigned int priobits, *priodata;
@@ -302,6 +330,7 @@ unsigned int priobits, *priodata;
   return &(pe->data);
 }
 
+/** Dequeue an entry */
 void *CqsPrioqDequeue(pq)
 prioq pq;
 {
@@ -499,6 +528,7 @@ prioq pq;
   return data;
 }
 
+/** Initialize a Queue and its three internal queues (for positive, negative, and zero priorities) */
 Queue CqsCreate(void)
 {
   Queue q = (Queue)CmiAlloc(sizeof(struct Queue_struct));
@@ -513,6 +543,7 @@ Queue CqsCreate(void)
   return q;
 }
 
+/** Delete a Queue */
 void CqsDelete(Queue q)
 {
   CmiFree(q->negprioq.heap);
@@ -535,6 +566,8 @@ int CqsEmpty(Queue q)
   return (q->length == 0);
 }
 
+
+/** Enqueue a message into the queue in a manner consistent with the specified strategy and priority */
 void CqsEnqueueGeneral(Queue q, void *data, int strategy, 
            int priobits,unsigned int *prioptr)
 {
@@ -629,6 +662,7 @@ void CqsEnqueue(Queue q, void *data)
   q->length++; if (q->length>q->maxlen) q->maxlen=q->length;
 }
 
+/** Retrieve the highest priority message (one with most negative priority) */
 void CqsDequeue(Queue q, void **resp)
 {
   if (q->length==0) 
@@ -760,3 +794,5 @@ void CqsEnumerateQueue(Queue q, void ***resp){
   CmiFree(result);
 }
 
+
+/** @} */
index 2b4bba4573c3995115b769ea0ce05d3477c8a0e5..b9793283ae98f869a1edf0c7495c55cc81474c64 100644 (file)
@@ -9,6 +9,13 @@
 #define QUEUEING_H
 /*#define FASTQ*/
 
+
+/** 
+   @addtogroup CharmScheduler
+   @{
+ */
+
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -19,6 +26,8 @@ extern "C" {
 #ifndef CLONGBITS
 #define CLONGBITS ((unsigned int) (sizeof(CmiInt8)*8))
 #endif
+
+/** Stores a variable bit length priority */
 typedef struct prio_struct
 {
   unsigned short bits;
@@ -27,23 +36,25 @@ typedef struct prio_struct
 }
 *prio;
 
+/** An untyped double ended queue stored in a circular buffer, with internal space for 4 entries */
 typedef struct deq_struct
 {
   /* Note: if head==tail, circ is empty */
-  void **bgn; /* Pointer to first slot in circular buffer */
-  void **end; /* Pointer past last slot in circular buffer */
-  void **head; /* Pointer to first used slot in circular buffer */
-  void **tail; /* Pointer to next available slot in circular buffer */
-  void *space[4]; /* Enough space for the first 4 entries */
+  void **bgn; /**< Pointer to first slot in circular buffer */
+  void **end; /**< Pointer past last slot in circular buffer */
+  void **head; /**< Pointer to first used slot in circular buffer */
+  void **tail; /**< Pointer to next available slot in circular buffer */
+  void *space[4]; /**< Enough space for the first 4 entries */
 }
 *deq;
 
 #ifndef FASTQ
+/** An element in a priority queue, which contains a deque and some other stuff. */
 typedef struct prioqelt_struct
 {
   struct deq_struct data;
-  struct prioqelt_struct *ht_next; /* Pointer to next bucket in hash table. */
-  struct prioqelt_struct **ht_handle; /* Pointer to pointer that points to me (!) */
+  struct prioqelt_struct *ht_next; /**< Pointer to next bucket in hash table. */
+  struct prioqelt_struct **ht_handle; /**< Pointer to pointer that points to me (!) */
   struct prio_struct pri;
 }
 *prioqelt;
@@ -51,10 +62,10 @@ typedef struct prioqelt_struct
 typedef struct prioqelt_struct
 {
   struct deq_struct data;
-  struct prioqelt_struct *ht_left; /* Pointer to left bucket in hash table. */
-  struct prioqelt_struct *ht_right; /* Pointer to right bucket in hash table. */
-  struct prioqelt_struct *ht_parent; /* Pointer to the parent bucket in the hash table */
-  struct prioqelt_struct **ht_handle; /* Pointer to pointer in the hashtable that points to me (!) */
+  struct prioqelt_struct *ht_left; /**< Pointer to left bucket in hash table. */
+  struct prioqelt_struct *ht_right; /**< Pointer to right bucket in hash table. */
+  struct prioqelt_struct *ht_parent; /**< Pointer to the parent bucket in the hash table */
+  struct prioqelt_struct **ht_handle; /**< Pointer to pointer in the hashtable that points to me (!) */
   struct prio_struct pri;
   /*  int deleted; */
 }
@@ -68,11 +79,12 @@ typedef struct prioqelt_struct
 /*#endif */
 
 /*#ifndef FASTQ*/
+/** A priority queue, implemented as a heap of prioqelts */
 typedef struct prioq_struct
 {
-  int heapsize;
+  int heapsize;  /**< An array of prioqelt's */
   int heapnext;
-  prioqelt *heap;
+  prioqelt *heap; /**< An array of prioqelt's */
   prioqelt *hashtab;
   int hash_key_size;
   int hash_entry_size;
@@ -91,13 +103,14 @@ typedef struct prioq1_struct
 */
 
 /*#ifndef FASTQ*/
+/** A set of 3 queues: a positive priority prioq_struct, a negative priority prioq_struct, and a zero priority deq_struct */
 typedef struct Queue_struct
 {
   unsigned int length;
   unsigned int maxlen;
-  struct deq_struct zeroprio;
-  struct prioq_struct negprioq;
-  struct prioq_struct posprioq;
+  struct deq_struct zeroprio; /**< A double ended queue for zero priority messages */
+  struct prioq_struct negprioq; /**< A priority queue for negative priority messages */
+  struct prioq_struct posprioq; /**< A priority queue for negative priority messages */
 }
 *Queue;
 /*#else
@@ -134,4 +147,6 @@ prio CqsGetPriority(Queue);
 };
 #endif
 
+/** @} */
+
 #endif