Changes between Version 15 and Version 16 of Libraries

Timestamp:

05/22/23 20:18:27 (3 years ago)

Author:

siegel

Comment:

--

Libraries

@@ -55 +55 @@
 
 === Types
-* `$message`
-* `$gcomm`
-* `$comm`
+* `$message`: A message consists of data and meta-data.  The data is a finite sequence of objects, all of the same type.  The meta-data consists of 3 integers: the source, destination, and tag.   The source identifies the process that sent the message.  The destination identifies the process to which the message is sent.   Both `source` and `destination` are "places", which are nonnegative integer IDs that abstract places from which messages are sent or received.   Typically, a single place is associated to each process in a message-passing system, but this is not required.  The tag is an additional nonnegative integer that can be used to represent anything the user wants; the receiving process may select a message based on the tag.  
+* `$gcomm`: This is an opaque handle to an object that stores the state of the message-passing system.  In particular, the buffered messages (those that have been sent, but not yet received) are stored in the gcomm.  
+* `$comm`:  Each place has its own comm, an opaque handle local to that place that is used to access all message-passing functions (e.g., sends and receives) at that place.  It contains a reference to the gcomm. 
 
 === Constants
-* `$COMM_ANY_SOURCE`
-* `$COMM_ANY_TAG`
+* `$COMM_ANY_SOURCE`: a constant that can be used as the source argument in a dequeue operation to indicate that a message may be taken from any source
+* `$COMM_ANY_TAG`: a constant that can be used as the tag argument in a dequeue operation to indicate that a message with any tag may be selected
 
 === Functions
 * `$atomic_f $message $message_pack(int source, int dest, int tag, const void *data, int size)`
+  * Creates a new message with the given meta-data, and the data taken from the memory region that begins at `data` and extends for `size` bytes.  The data is copied into the new message object.  The source, destination, and tag must be nonnegative.  The size may be 0.
 * `$atomic_f int $message_source($message message)`
+  * Gets the source of the message.
 * `$atomic_f int $message_tag($message message)`
+  * Gets the tag of the message.
 * `$atomic_f int $message_dest($message message)`
+  * Gets the destination of the message.
 * `$atomic_f int $message_size($message message)`
+  * Gets the size of the message data (in bytes).
 * `$atomic_f void $message_unpack($message message, void *buf, int size)`
+  * Extracts the data from a message, storing it in the buffer that starts at `buf`.  The argument `size` must be greater than or equal to the size of message, else an error occurs.
 * `$atomic_f $gcomm $gcomm_create($scope scope, int size)`
+  * Allocates a new gcomm object that will be stored in the heap of the specified scope.  The `size` is the number of "places" that will be associated to this gcomm.  The place IDs range from 0 to `size`-1 (inclusive).
 * `$atomic_f int $gcomm_destroy($gcomm gcomm, void * junkMsgs)`
 * `$atomic_f void $gcomm_dup($comm comm, $comm newcomm)`