~bzr-pqm/bzr/bzr.dev

Patch pools

***********

*Patch pools* are an optimization for efficient storage of related

branches.  They are not required for the first release.

Revisions, inventories, and file states are identified in Bazaar-NG by

universally unique hashes, and they are never modified once they are

created.  Objects which are common between branches may therefore be

stored only once and referenced from each branch.  Various strategies

are available for doing this.

Objects can be held hard-linked between related branches on

filesystems that support hardlinks.  This provides automatic reference

counting as branches are deleted.

It is common to have several branches of the same project on a

machine, with many objects in common.  These can be configured with

each other on the pool path.  The parent should be the default pool

path when creating a new branch.

Each user might also have a pool that acts as a cache of all remote

revisions.  Such a cache might use some kind of least-recently-used

policy to limit its size.

The user might nominate a series or hierarchy of pools to be searched for a

patch; these might be progressively on the local machine, local

network and remotely.  

A system like the supermirror might make good use of a pool that

gradually accumulates all public objects in the world, and stores

branches very cheaply.

One complication is garbage collection.  Naive implementations that

store references from branches into the pool will not be able to

detect objects that are no longer referenced by any active branch; as

branches are created and deleted over time such objects will

accumulate.  This may not be a problem in many cases, given the

relative abundance of disk compared to programmer time, and the

relatively small number of long branches that are discarded.  There

are some partial solutions:

* Keep a reference count for each object.  There is no problem of

  circular references.  However, keeping the count accurately requires

  that branches are never lost or deleted other than through the

  correct mechanism.

* From time to time, building a new pool including only objects from

  active branches.

* Keeping a pool that holds only patches known to be available from

  elsewhere, so the pool is only a cache and never the single source

  of a particular object.  Such a pool can then be discarded at will

  and the objects will be re-fetched from their original source.

This last point suggests that new objects should never be written

solely into a pool, because of the risk that they might be

accidentally lost.

Using the parent on the default pool path allows for varying

greed or laziness in fetching objects.  By default, objects might be

read only as necessary, and then stored in the local cache.  If the

user wants to keep the whole history available locally that could be

specified with a ``--greedy`` option when making the branch, or

through later pulling down the history.