gitlab.com/SkynetLabs/skyd@v1.6.9/skymodules/renter/proto/README.md (about)

     1  # Proto
     2  Coming Soon...
     3  
     4  ## Subsystems
     5  
     6  ### Contracts
     7  Coming Soon...
     8  
     9  #### SafeContract
    10  Coming Soon...
    11  
    12  #### ContractSet
    13  Coming Soon...
    14  
    15  ### Downloader
    16  Coming Soon...
    17  
    18  ### Editor
    19  Coming Soon...
    20  
    21  ### FileSection
    22  Coming Soon...
    23  
    24  ### FormContract
    25  Coming Soon...
    26  
    27  ### Merkle Roots
    28  Coming Soon...
    29  
    30  ### Negotiate
    31  Coming Soon...
    32  
    33  ### Reference Counter Subsystem
    34  **Key Files**
    35   - [refcounter.go](./refcounter.go)
    36  
    37  The reference counter is a ledger that accompanies the contract and keeps track 
    38  of the number of references to each sector. The number of references starts at
    39  one and increases as the user creates new backups of this contract. It decreases
    40  as the user deletes backups or deletes the siafile itself. Once the counter
    41  reaches zero, there is no way for the user to use the data stored in the sector.
    42  At this moment the sector can be reused by storing new data in it or it can be
    43  dropped when renewing the contract, so the user doesn't pay for it anymore.
    44  
    45  #### The Reference Counter
    46  
    47  The reference counter struct exposes a simple API aimed at manipulating the
    48  counters that it holds. One of the few complexities that might not be 
    49  immediately obvious is that before performing any mutating operation, the caller
    50  need to start an update session by invoking `callStartUpdate`. This update
    51  session will use the WAL in order to ensure that all operations are ACID. After
    52  finishing a given set of mutations, the caller needs to invoke 
    53  `callCreateAndApplyTransaction` in order for the updates to be written to disk.
    54  Before being written to disk, the updates are only reflected in a set of 
    55  in-memory data structures. This ensures that any operation with the reference 
    56  counter between the creation and application of the update will work with 
    57  the updated data. In order to finish an update the caller needs to invoke 
    58  `callUpdateApplied` in order to close the update session.
    59  
    60  Each reference counter is created and deleted together with a contract, and this
    61  contract is responsible for its proper maintenance. The counts should be updated
    62  on backup creation/deletion and on file deletion.
    63  
    64  ##### Inbound Complexities
    65   - `callCount` can be used to fetch the value of a given counter
    66   - `callStartUpdate` can be used to start a new series of ACID updates
    67   - `callAppend` and `callDropSectors` can be used to add and remove sectors as 
    68   they are added or removed to/from the contract
    69      - `contract.makeUpdateRefCounterAppend` uses `callAppend` to reflect the
    70      upload of new sectors to the contract
    71   - `callSwap` can be used to swap the positions of two counters in the file
    72   - `callIncrement`, `callDecrement`, and `callSetCount` can be used to adjust
    73   the value of a given counter
    74   - `callCreateAndApplyTransaction` is used to apply a set of updates to the file
    75   on disk
    76   - `callUpdateApplied` finished an update session
    77       - `contract.managedCommitAppend` and `contract.managedCommitTxns` use
    78       `callCreateAndApplyTransaction` (via the `contract.applyRefCounterUpdate`
    79       method) and `callUpdateApplied` in order to persist the changes they made 
    80       to disk
    81   - `callDeleteRefCounter` removes the entire reference counter file from disk
    82   
    83  ##### Outbound Complexities
    84   - `callCreateAndApplyTransaction` will use `writeaheadlog.WAL.NewTransaction` 
    85   in order to start a new WAL transaction. It will then use this transaction to 
    86   apply the given updates and then it will close it.
    87  
    88  ### Renew
    89  Coming Soon...
    90  
    91  ### Seeds
    92  Coming Soon...
    93  
    94  ### Session
    95  Coming Soon...