Correction in doc for Isomalloc - individual pupping is no longer supported
[charm.git] / doc / converse / isomalloc.tex
1 \section{Isomalloc}
2
3 It is occasionally useful to allocate memory at a globally unique
4 virtual address.  This is trivial on a shared memory machine
5 (where every address is globally unique); but more difficult on
6 a distributed memory machine (where each node has its own separate data
7 at address 0x80000000).
8 Isomalloc provides a uniform interface for allocating globally unique
9 virtual addresses.
10
11 Isomalloc can thus be thought of as a software distributed shared
12 memory implementation; except data movement between
13 processors is explicit (by making a subroutine call), not on demand
14 (by taking a page fault).
15
16 Isomalloc is useful when moving highly interlinked data structures
17 from one processor to another, because internal pointers will still
18 point to the correct locations, even on a new processor.  This is especially
19 useful when the format of the data structure is complex or unknown, as with
20 thread stacks.
21
22 \function{void *CmiIsomalloc(int size)}
23 \index{CmiIsomalloc}
24 \desc{Allocate size bytes at a unique virtual address.  Returns
25 a pointer to the allocated region.
26
27 CmiIsomalloc makes allocations with page granularity (typically several
28 kilobytes); so it is not recommended for small allocations.
29 }
30
31 \function{void CmiIsomallocFree(void *doomedBlock)}
32 \index{CmiIsomallocFree}
33 \desc{Release the given block, which must have been previously
34 returned by CmiIsomalloc.  Also releases the used virtual
35 address range, which the system may subsequently reuse.
36
37 After a CmiIsomallocFree, references to that block will 
38 likely result in a segmentation violation.  It is illegal to
39 call CmiIsomallocFree more than once on the same block.
40 }
41
42 \function{void CmiIsomallocPup(pup\_er p,void **block)}
43 \index{CmiIsomallocPup}
44 \desc{Pack/Unpack the given block.  This routine can be used to move
45 blocks across processors, save blocks to disk, or checkpoint blocks.
46
47 After unpacking, the pointer is guaranteed
48 to have the same value that it did before packing.
49 }
50
51 Note- Use of this function to pup individual blocks is not supported any longer.
52 All the blocks allocated via CmiIsomalloc are pupped by the RTS as one single
53 unit.
54
55 \function{int CmiIsomallocLength(void *block);}
56 \index{CmiIsomallocLength}
57 \desc{
58 Return the length, in bytes, of this isomalloc'd block.
59 }
60
61 \function{int CmiIsomallocInRange(void *address)}
62 \index{CmiIsomallocInRange}
63 \desc{Return 1 if the given address may have been previously allocated to 
64 this processor using Isomalloc; 0 otherwise.  CmiIsomallocInRange(malloc(size))
65 is guaranteed to be zero; CmiIsomallocInRange(CmiIsomalloc(size))
66 is guaranteed to be one.
67 }