diff --git a/mps/code/arena.c b/mps/code/arena.c index 2d460e06c35..519a85d735b 100644 --- a/mps/code/arena.c +++ b/mps/code/arena.c @@ -758,7 +758,7 @@ void ArenaChunkRemoved(Arena arena, Chunk chunk) * This is a primitive allocator used to allocate pages for the arena * Land. It is called rarely and can use a simple search. It may not * use the Land or any pool, because it is used as part of the - * bootstrap. + * bootstrap. See design.mps.bootstrap.land.sol.alloc. */ static Res arenaAllocPageInChunk(Addr *baseReturn, Chunk chunk, Pool pool) @@ -866,7 +866,7 @@ static void arenaExcludePage(Arena arena, Range pageRange) * The arena's free land can't get memory for its block pool in the * usual way (via ArenaAlloc), because it is the mechanism behind * ArenaAlloc! So we extend the block pool via a back door (see - * arenaExtendCBSBlockPool). + * arenaExtendCBSBlockPool). See design.mps.bootstrap.land.sol.pool. * * Only fails if it can't get a page for the block pool. */ diff --git a/mps/code/poolmfs.c b/mps/code/poolmfs.c index ed1c0343aba..90232621c25 100644 --- a/mps/code/poolmfs.c +++ b/mps/code/poolmfs.c @@ -249,7 +249,8 @@ static Res MFSAlloc(Addr *pReturn, Pool pool, Size size, if(f == NULL) { Addr base; - + + /* See design.mps.bootstrap.land.sol.pool. */ if (!mfs->extendSelf) return ResLIMIT; diff --git a/mps/design/bootstrap.txt b/mps/design/bootstrap.txt index 7eb79df1475..8615aee0f99 100644 --- a/mps/design/bootstrap.txt +++ b/mps/design/bootstrap.txt @@ -67,13 +67,23 @@ Arena's free land _`.land`: Before the arena can allocate memory, a range of addresses must be inserted into the arena's free land (so that the free land can hand out memory from this range). But before addresses can be inserted -into the arena's free land, the arena must be able to allocate memory -(to store the nodes in the tree representing those addresses). +into the arena's free land, the free land's block pool must have +memory from the arena to store the nodes in the tree representing +those addresses. _`.land.sol`: The arena has two "back door" mechanisms and uses them -in combination. First, there is a mechanism for allocating a block of -memory directly from a chunk, bypassing the free land; second, the MFS -pool class has a mechanism for extending it with a block of memory. +in combination. + +_`.land.sol.alloc`: First, there is a mechanism for allocating a +page of memory directly from a chunk, bypassing the free land. + +_`.land.sol.pool`: Second, the free land's block pool has an option to +prevent it extending itself by allocating memory from the arena. +Instead, it fails allocations with ``ResLIMIT``. The free land's +block pool also has a mechanism, ``MFSExtend`` to extend it with a +block of memory. When the free land fails with ``ResLIMIT`` the arena +uses `.land.sol.alloc`_ to provide it with memory. + Document History @@ -81,15 +91,19 @@ Document History - 2015-09-01 GDR_ Initial draft. +- 2016-02-25 RB_ Improving description of arena free land bootstrap + and cross-referencing from source code. + .. _GDR: http://www.ravenbrook.com/consultants/gdr/ +.. _RB: http://www.ravenbrook.com/consultants/rb/ Copyright and License --------------------- -Copyright © 2015 Ravenbrook Limited. All rights reserved. -. This is an open source license. Contact -Ravenbrook for commercial licensing options. +Copyright © 2015-2016 Ravenbrook Limited +. All rights reserved. This is an open +source license. Contact Ravenbrook for commercial licensing options. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are