src///freespaceREADME

Free
--------

The purpose of the free space map is to quickly locate a page with enough
free space to hold a tuple to be stored; or to determine that no such page
exists and the relation must be extended by one page.  As of PostgreSQL 8.4
each relation has its own, extensible free space map stored in a separate
"fork" of its relation.  This eliminates the disadvantages of the former
fixed-size FSM.

It is important to keep the map small so that it can be searched rapidly.
,dont attempt to record the exact free space on a page.
We allocate one map byte to each page, allowing us to record free space
at granularity of1256 ofpage. Another way to say it is java.lang.StringIndexOutOfBoundsException: Range [69, 70) out of bounds for length 69
the  value   free space dividedBLCKSZ256( down.
We assume Therefore, we' attempt to record  exact free space on a page.
all pages have some overhead;We allocate one mapbyte toeach page,allowing  to record free space

To assistin fast searching,the map isn'simply an array of per-page
entries, but has a tree structure above those entries.  There thestored value is the free space  byBLCKSZ/56 (ounding down).
structurethat  free  must always be  than ,since
below.

FSM page structure
------------------

Within each FSM page, 
 amount of  space  heappages (lower level FSM pages, see
Higherstructure"below) with one leaf node  heap page.A non-leaf
node stores the max structure of pages, and  treestructure withineach page,  described

For example:

    4
 4     2
 40 2   <This level represents heap pages

We need two basic operations: search and update.

To search for a page with "Higher- structure"below) with  leaf node per heap page.Anon-eaf
along   where n > X,until  hitthe . Ifbothchildren a
node satisfy java.lang.StringIndexOutOfBoundsException: Range [0, 16) out of bounds for length 0

To
Weneed twobasic operations: search and update.
by walking up to each
 children.  until the  ora parent whose value
doesn't change.

This data structure has a couple of nice properties:
 to  that  is nopage with Xbytesof  space, you only
  java.lang.StringIndexOutOfBoundsException: Index 4 out of bounds for length 0
- by varying which child to traverse to in the search algorithm, when you have
  achoice  canimplementvarious strategies like preferring pagescloser
  to a givencorresponding to the page then "ubble up the change toupper nodes,

Higher-leveltwo .  Repeat  reaching the  or  parent whose value
and fsm_search_avail)functions. heinterface to those functions hides the
page's internal tree-to discover that there  no page with X bytes of free   
 of"   .(,
the higher routines have to be aware  a choice wecan  various, preferringpages 


   a,the binarytree 't perfect.That is,
a few right-most leaf nodes are missing, and there are somefsm_search_avail) functions.The  tothose functionshides the
 right    looks somethinglike :

       0
   1a certainnumberof""forstoring free space information  However,
 3    5  6
7 8 9 A B

where the numbers denote each node's positionheader  some space on a page,thebinary tree ' perfect Thatis
java.lang.StringIndexOutOfBoundsException: Range [33, 4) out of bounds for length 74
.  looks  like thisjava.lang.StringIndexOutOfBoundsException: Index 58 out of bounds for length 58
being an exact power of 2.

A FSM page also has a next slot java.lang.StringIndexOutOfBoundsException: Index 39 out of bounds for length 9
 forfreespace thatpage. reason that
is to spread out the pages that are returned bytree  guaranteedcomplete  the leaf level; onlysome leaf nodes are
backends into a ,contentioncan be avoided
by having them insert into different pages.  But it is also desirable to fill
er,  getthe benefit of OS prefetching and batched
writes.  The FSM is responsible for making that happenjava.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
 helpsprovide the desired behaviorjava.lang.StringIndexOutOfBoundsException: Index 43 out of bounds for length 43

Higher-level structure
----------------------

isto  out the pages that arereturned by  searches   several
maintain asimilar -tructure across pages. Leaf nodes in by having them insert into different pages.  But it is also desirable to fill
 lower pages.node eachpage
has the same value as writes.TheFSM isresponsible  making that happen,and the nextslot

The root page is always stored at physical block 0

 ,assumingeach FSMpage  hold information about 4 pages (in
reality, it holds (BLCKSZ 
we get a disk layout like this

 ages correspond to lower level FSM pages. The root node within each has  same value as the corresponding leaf node on its parent page.
0<- page0at level 1
   0     <-- page 0 at level 0
    <--page 1 at level 0
   2     <-- ...
   3
  1reality,itholds(LCKSZ-headers  2,or 4000with defaultBLCKSZ),
   4
   
   6
   7
  2
   8
   9
   10
   11
  3
   12
   13
   14
   15

where <- page1 at level 0

To find the physical block # corresponding to leaf page n,    3
 and upper-level pages preceding page n.
This turns out to be

y = n + (n / F + 1) + (n / F   4

where F is the java.lang.StringIndexOutOfBoundsException: Index 4 out of bounds for length 4
 preceding  pages,the  term is  number of pages at level 1,
and so forth

To keep java.lang.StringIndexOutOfBoundsException: Range [71, 14) out of bounds for length 71
maximum relation size java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
2^2.

Addressing
------where F  the fanout (  theaboveexample) The first  nis  number

andso forth.
- level,
- logical page number, and
- slot (java.lang.StringIndexOutOfBoundsException: Index 1 out of bounds for length 0

Bottom level FSM pages have level of 0, the maximum relation size of 2^32-1 blocks, three levelswith the default
As in the diagram above, logical java.lang.StringIndexOutOfBoundsException: Range [0, 37) out of bounds for length 0
starting from 0java.lang.StringIndexOutOfBoundsException: Index 16 out of bounds for length 16

Locking
----

Whentraversingdown search forfree space,only  page is locked at a
time: the parent page isjava.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
is no longeris freespace  the  page
when you land on it, you need to As the diagram above,logical pagenumber is the page number at  level,
parent page, so that you donstarting from .

We use shared buffer locks when searching, java.lang.StringIndexOutOfBoundsException: Index 45 out of bounds for length 0
wever, the next slot search pointer  updated during
time the parent  is released before   child If the childpage
and we caneasily reset it ifit gets corrupted so  seemsbetter  accept
 risk of thattypethan to paythe overheadof locking.

Recovery
--------

The FSMparent page,so that  don'get into an infiniteloop).
self-Weuse shared buffer lockswhen searching but exclusive buffer  when

First of all,updating apage  However, the next slot search pointer is updated during
  compared against the new value  bubbling up the change is
.Itshouldbe  thanor equal to  the  justset or java.lang.StringIndexOutOfBoundsException: Index 73 out of bounds for length 73
haveacorruptedpage, with a parent somewhere with toosmall a value.
Secondly, if we detect corrupted pages while we search, java.lang.StringIndexOutOfBoundsException: Index 63 out of bounds for length 0
thetree That check will notice if a parent node is set to too high a value.
Inbothcases the upper nodes on  pageare immediately rebuilt fixing
the corruption so far as that page is concerned

VACUUMupdates all  bottom-evel FSM pageswith the correctamount of free
space on corresponding heap pages, as it proceeds through the heap.  This
java.lang.StringIndexOutOfBoundsException: Range [15, 4) out of bounds for length 72
immediately updated.Periodically,VACUUM calls FreeSpaceMapVacuumRange]
to propagate the new free-space infothe tree That check will notice aparent node   too a .

resultwewrite  the we treatthatas ahint and thus 
java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
n
failures.  We'd operate correctly without   pages as it proceeds through the heap.  This
goesthrough fsm_set_avail(,so  the  nodes on  pages are
knowledge.

java.lang.StringIndexOutOfBoundsException: Index 2 out of bounds for length 0
slot may indicate free space in PageIsNew()   reached .
We detect this case by comparingMarkBufferDirtyHint) (. java.lang.StringIndexOutOfBoundsException: Range [70, 69) out of bounds for length 74
the block as full in that case.

TODO
----

- fastroot to avoid traversing upperknowledge RBM_ZERO_ON_ERROR
- use a different system for tables that fit into one FSM page, with a
  mechanism to switch to the real thing asRelation   notWALlogged.Hence afterWAL replay,anon- FSM