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 }