emilytrau/lix
1
0
Fork 0
forked from lix-project/lix
Code Pull requests Activity

replace pseudo code by diagrams

Browse source 
change prose description to visually resemble the data structure
This commit is contained in:
Valentin Gagarin 2022-05-26 03:40:17 +02:00
parent db8703bcac
commit 445f753a82
1 changed files with 32 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

57
doc/manual/src/architecture/store/store.md
View file

@ -2,33 +2,49 @@
A Nix store is a collection of *store objects*. A Nix store is a collection of *store objects*.
A store object can hold arbitrary *data* and *references* to other store objects. A store object can hold
Nix makes no distinction if store objects are used as build inputs, build results, or build tasks.
```haskell - arbitrary *data*
data Store = Set StoreObject - *references* to other store objects.
data StoreObject = StoreObject { Nix makes no distinction if store objects are build inputs, build results, or build tasks.
data :: Data
, references :: Set Reference
}
```
A Nix store can *add*, *retrieve*, and *delete* store objects. A Nix store can *add*, *retrieve*, and *delete* store objects.
[ data ]
|
V
[ store ] ---> add ----> [ store' ] [ reference ]
<!-- -->
[ reference ]
|
V
[ store ] ---> get ----> [ store object ]
<!-- -->
[ reference ]
|
V
[ store ] --> delete --> [ store' ]
It can *perform builds*, that is, create new store objects by transforming build inputs into build outputs, using instructions from the build tasks. It can *perform builds*, that is, create new store objects by transforming build inputs into build outputs, using instructions from the build tasks.
[ reference ]
|
V
[ store ] --> build --(maybe)--> [ store' ] [ reference' ]
As it keeps track of references, it can [garbage-collect][garbage-collection] unused store objects. As it keeps track of references, it can [garbage-collect][garbage-collection] unused store objects.
```haskell
add :: Store -> Data -> (Store, Reference)
get :: Store -> Reference -> StoreObject
delete :: Store -> Reference -> Store
build :: Store -> Reference -> Maybe (Store, Reference) [ store ] --> collect garbage --> [ store' ]
collectGarbage :: Store -> Store
```
Store objects are [immutable][immutable-object]: once created, they do not change until they are deleted. Store objects are [immutable][immutable-object]: once created, they do not change until they are deleted.
@ -41,15 +57,6 @@ An added store object cannot have references, unless it is a build task.
Building a store object will add appropriate references, according to provided build instructions. Building a store object will add appropriate references, according to provided build instructions.
These references can only come from declared build inputs, and are not known to build instructions a priori. These references can only come from declared build inputs, and are not known to build instructions a priori.
```haskell
data Data = Data | Task BuildTask
data BuildTask = BuildTask {
instructions :: Reference
, inputs :: [Reference]
}
```
A store object cannot be deleted as long as it is reachable from a reference still in use. A store object cannot be deleted as long as it is reachable from a reference still in use.
Garbage collection will delete all store objects that cannot be reached from any reference in use. Garbage collection will delete all store objects that cannot be reached from any reference in use.