Class FileRepoStagedTransaction
Represents a staged transaction for a file repository: a transaction that records all of its deletions in a single journal file and is committed in two calls, StageAsync(CancellationToken) before the application commits its database and CommitAsync(CancellationToken) after.
Namespace: FulcrumFS
Assembly: FulcrumFS.Local.dll
Syntax
public sealed class FileRepoStagedTransaction : IFileRepoStagedTransaction, IAsyncDisposableRemarks
Use a staged transaction when one application transaction deletes many files. An ordinary FileRepoTransaction writes, flushes to disk and holds open a marker for every file it deletes until it commits. A staged transaction records its deletions in memory, and StageAsync(CancellationToken) writes them all to one journal file, flushes it once and holds it open until the transaction commits or rolls back.
The commit ordering rule is the same as for an ordinary transaction: call StageAsync(CancellationToken), commit the database, then commit the FileRepoStage it returned. A staged transaction has no commit method of its own, so it cannot be committed without being staged first. When nothing needs to happen between the two steps, StageAndCommitAsync(CancellationToken) performs both. Disposing the transaction before its stage has been committed rolls it back.
Files added by a staged transaction are tracked per file, as in an ordinary transaction, and are committed or rolled back together with its deletions. If the process ends after staging and before the stage has been committed, the cleaner resolves the files listed in the journal through the callback passed to CleanAsync(TimeSpan, Func<FileId, Task<IndeterminateResolution>>?, CancellationToken), as it does for indeterminate files.
Other repository operations do not consult journals, except EnumerateFilesAsync(CancellationToken): it reports a file whose deletion is staged as indeterminate, and one whose deletion a staged transaction committed in a deferred delete mode as pending deletion. Another transaction can still delete such a file, as it can any file pending deletion, and both deletions converge. Like any deleted main file, it stays readable until a cleanup pass removes it.
A repository whose FormatVersion is 1 must not contain journals, because FulcrumFS 1.0.x may clean it. On such a repository StageAsync(CancellationToken) writes, flushes and holds the marker of each recorded deletion as an ordinary transaction does, and committing the stage commits and rolls back each deletion as an ordinary transaction does, so committed deletions get the usual per-file delete markers. The API, the commit ordering rule and the guarantees are the same; only the cost of staging grows with the number of files.
Properties
| Name | Description |
|---|---|
| Repository | Gets the file repository associated with this transaction. |
Methods
| Name | Description |
|---|---|
| AddAsync(FileStream, bool, IFileProcessingPipelineSelector, CancellationToken) | Adds a new file to the repository with the specified file stream, processing it through the specified file pipeline. |
| AddAsync(Stream, string, bool, IFileProcessingPipelineSelector, CancellationToken) | Adds a new file to the repository with the specified stream and extension, processing it through the specified file pipeline. |
| DeleteAsync(FileId, CancellationToken) | Deletes an existing or tentatively added file from the repository by its file ID. |
| DisposeAsync() | Disposes the transaction, rolling it back unless its stage has been committed. |
| RollbackAsync(CancellationToken) | Rolls back the transaction, discarding the files it added and the deletions it recorded, and deleting its journal if it was staged. The transaction cannot be used afterwards. |
| StageAndCommitAsync(CancellationToken) | Stages the transaction and commits the stage, for callers that have no database commit to make between the two steps. |
| StageAsync(CancellationToken) | Stages the transaction: writes the deletions it recorded to a delete journal, flushes the journal to disk and holds it open, and returns the stage that commits the transaction. Call this before committing the application's database, and commit the stage after. |
| TryDeleteAsync(FileId, CancellationToken) | Deletes an existing or tentatively added file from the repository by its file ID if it exists, and reports whether it did. |
Explicit Interface Implementations
| Name | Description |
|---|---|
| IFileRepoStagedTransaction.AddAsync(FileStream, bool, IFileProcessingPipelineSelector, CancellationToken) | Adds a new file to the repository from the specified file stream, taking the extension from the stream's file name, and processes it through the specified pipeline. |
| IFileRepoStagedTransaction.AddAsync(Stream, string, bool, IFileProcessingPipelineSelector, CancellationToken) | Adds a new file to the repository from the specified stream and extension, and processes it through the specified pipeline. |
| IFileRepoStagedTransaction.Repository | Gets the repository the transaction belongs to. |
| IFileRepoStagedTransaction.StageAsync(CancellationToken) | Stages the transaction: makes the deletions it recorded durable and returns the stage that commits the transaction. Call this before committing the application's database, and commit the stage after. |