Added CmiIsomalloc documentation (CmiIsomalloc is a generalization of
authorOrion Lawlor <olawlor@acm.org>
Tue, 11 Dec 2001 22:06:11 +0000 (22:06 +0000)
committerOrion Lawlor <olawlor@acm.org>
Tue, 11 Dec 2001 22:06:11 +0000 (22:06 +0000)
CMK_THREADS_USE_ISOMALLOC same-virtual-address-everywhere thread stacks).

doc/converse/cmi.tex

index ce16ef5d94207ab61e88a839c113e829c890d693..aac8339122deea1cb346049d564a9d10decd558e 100644 (file)
@@ -871,3 +871,63 @@ numbers of children of \uw{procNum} in the spanning tree.}
 \desc{This function fills the array \uw{children} with node
 numbers of children of \uw{nodeNum} in the spanning tree.}
 
 \desc{This function fills the array \uw{children} with node
 numbers of children of \uw{nodeNum} in the spanning tree.}
 
+\section{Isomalloc}
+
+It is occasionally useful to allocate memory at a globally unique
+virtual address.  This is trivial on a shared memory machine
+(where every address is globally unique); but more difficult on
+a distributed memory machine (where each node has its own 0x40000000).
+Isomalloc provides a uniform interface for allocating globally unique
+virtual addresses.
+
+Isomalloc can thus be thought of as a software distributed shared
+memory implementation; except data movement between
+processors is explicit (by making a subroutine call), not on demand
+(by taking a page fault).
+
+Isomalloc is useful when moving highly interlinked data structures
+from one processor to another, because internal pointers will still
+point to the correct locations, even on a new processor.  This is especially
+useful when the format of the data structure is complex or unknown, as with
+thread stacks.
+
+\function{void *CmiIsomalloc(int size,CmiIsomallocBlock *retBlock)}
+\index{CmiIsomalloc}
+\desc{Allocate size bytes at a unique virtual address.  Returns
+a pointer to the allocated region, and fills out the given 
+CmiIsomallocBlock structure.
+
+CmiIsomalloc makes allocations with page granularity (typically several
+kilobytes); so it is not recommended for small allocations.
+}
+
+\function{void CmiIsomallocFree(CmiIsomallocBlock *doomedBlock)}
+\index{CmiIsomallocFree}
+\desc{Release the given block, which must have been previously
+filled out by CmiIsomalloc.  Also releases the used virtual
+address range, which the system may subsequently reuse.
+
+After a CmiIsomallocFree, references to that block will 
+likely result in a segmentation violation.  It is illegal to
+call CmiIsomallocFree more than once on the same block.
+}
+
+\function{void *CmiIsomallocPup(pup\_er p,CmiIsomallocBlock *block)}
+\index{CmiIsomallocPup}
+\desc{Pack/Unpack the given block.  This routine can be used to move
+blocks across processors, save blocks to disk, or checkpoint blocks.
+
+Returns a pointer to the allocated region.  The pointer is guaranteed
+to have the same value after unpacking that it did before packing.
+}
+
+\function{int CmiIsomallocInRange(void *address)}
+\index{CmiIsomallocInRange}
+\desc{Return 1 if the given address may have been previously allocated to 
+this processor using Isomalloc; 0 otherwise.  CmiIsomallocInRange(malloc(size))
+is guaranteed to be zero for any value of size.
+}
+
+
+
+