← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/repository.txt

  • Committer: Florent Gallaire
  • Date: 2017-03-17 10:39:02 UTC
  • mto: This revision was merged to the branch mainline in revision 6622.
  • Revision ID: fgallaire@gmail.com-20170317103902-xsmafws9vn8rczx9
Fix for Windows and 32-bit platforms buggy gmtime().

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/repository.txt
8
8
:Date: 2007-07-08
9
9
 
10
10
This document describes the services repositories offer and need to offer
11
 
within brlib.
 
11
within bzrlib.
12
12
 
13
13
 
14
14
.. contents::
44
44
                    introduced by a set of revisions in some cheap form, insert
45
45
                    data from a stream, validate data during insertion.
46
46
Garbage Collection  Exclusive lock the repository preventing readers.
47
 
Revert              Delta from working tree to historical tree, and then 
 
47
Revert              Delta from working tree to historical tree, and then
48
48
                    arbitrary file access to obtain the texts of differing
49
49
                    files.
50
50
Uncommit            Revision graph access.
98
98
                     Scan the inventory data introduced during the selected
99
99
                     revisions, and grab the on disk data for the found
100
100
                     file texts, annotation region data, per-file-graph
101
 
                     data, piling all this into a stream. 
 
101
                     data, piling all this into a stream.
102
102
Garbage Collection   Basically a mass fetch of all the revisions which
103
103
                     branches point at, then a bait and switch with the old
104
104
                     repository thus removing unreferenced data.
106
106
                     to, inventory extraction of that revision,
107
107
                     dirblock-order file text extract for files that were
108
108
                     different.
109
 
Uncommit             Revision graph access to synthesise pending-merges 
 
109
Uncommit             Revision graph access to synthesise pending-merges
110
110
                     linear access down left-hand-side, with is_ancestor
111
111
                     checks between all the found non-left-hand-side
112
112
                     parents.
113
113
Status               Lookup the revisions added by pending merges and their
114
114
                     commit messages. Then an inventory difference between
115
115
                     the trees involved, which may include a working tree.
116
 
                     If there is a working tree involved then the file 
 
116
                     If there is a working tree involved then the file
117
117
                     fingerprint for cache-misses on files will be needed.
118
118
                     Note that dirstate caches most of this making
119
119
                     repository performance largely irrelevant: but if it
246
246
  offset for the data record in the knit, the byte length for the data
247
247
  record in the knit and the no-end-of-line flag.
248
248
 
249
 
Its important to note that knit repositories cannot be regenerated by
 
249
It's important to note that knit repositories cannot be regenerated by
250
250
scanning .knits, so a mapped index is still irreplaceable and must be
251
251
transmitted on push/pull.
252
252
 
256
256
delta-compressed ever. Likewise signatures do not need the parent pointers
257
257
at all as there is no 'signature graph'.
258
258
 
259
 
Data 
 
259
Data
260
260
----
261
261
 
262
262
Moving to pack based repositories
271
271
interesting to have it be deterministic based on content, but there are no
272
272
specific problems we have solved by doing that, and doing so would require
273
273
hashing the full file. OTOH hashing the full file is a cheap way to detect
274
 
bit-errors in transfer (such as windows corruption).
 
274
bit-errors in transfer (such as windows corruption). Non-reused file names
 
275
are required for data integrity, as clients having read an index will
 
276
readv at arbitrary times later.
275
277
 
276
278
Discovery of files
277
279
~~~~~~~~~~~~~~~~~~
298
300
Choosing compression/delta support
299
301
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
300
302
 
301
 
 
 
303
Caching and writeing of data
 
304
============================
 
305
 
 
306
Repositories try to provide a consistent view of the data within them
 
307
within a 'lock context'.
 
308
 
 
309
Locks
 
310
-----
 
311
 
 
312
Locks come in two flavours - read locks and write locks. Read locks allow
 
313
data to be read from the repository. Write locks allow data to be read and
 
314
signal that you intend to write data at some point. The actual writing of
 
315
data must take place within a Write Group.
 
316
 
 
317
Write locks provide a cache of repository data during the period of the
 
318
write lock, and allow write_groups to be acquired. For some repositories
 
319
the presence of a write lock is exclusive to a single client, for others
 
320
which are lock free or use server side locks (e.g.  svn), the write lock
 
321
simply provides the cache context.
 
322
 
 
323
Write Groups
 
324
------------
 
325
 
 
326
Write groups are the only allowed means for inserting data into a
 
327
repository.  These are created by ``start_write_group``, and concluded by
 
328
either ``commit_write_group`` or ``abort_write_group``.  A write lock must
 
329
be held on the repository for the entire duration.  At most one write
 
330
group can be active on a repository at a time.
 
331
 
 
332
Write groups signal to the repository the window during which data is
 
333
actively being inserted. Several write groups could be committed during a
 
334
single lock.
 
335
 
 
336
There is no guarantee that data inserted during a write group will be
 
337
invisible in the repository if the write group is not committed.
 
338
Specifically repositories without atomic insertion facilities will be
 
339
writing data as it is inserted within the write group, and may not be able
 
340
to revert that data - e.g. in the event of a dropped SFTP connection in a
 
341
knit repository, inserted file data will be visible in the repository. Some
 
342
repositories have an atomic insertion facility, and for those
 
343
all-or-nothing will apply.
 
344
 
 
345
The precise meaning of a write group is format specific. For instance a
 
346
knit based repository treats the write group methods as dummy calls,
 
347
simply meeting the api that clients will use. A pack based repository will
 
348
open a new pack container at the start of a write group, and rename it
 
349
into place at commit time.
302
350
 
303
351
 
304
352
..