Method StageAsync

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.

Declaration

public Task<FileRepoStage> StageAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	A cancellation token that cancels the call while it waits: for another call on this transaction to finish, and on a version 1 repository for a marker that is in use. It is not observed otherwise, and nothing has been staged when it cancels the call.

Returns

Type	Description
Task<FileRepoStage>

Remarks

Once the transaction is staged, files can no longer be added to it or deleted by it. If it recorded no deletions, no journal is written and committing the stage only commits the files it added.

A failure to write the journal is thrown, and so is a cancellation. Nothing has been staged in that case, and the journal that could not be completed is removed: the transaction can be staged again or rolled back, disposing it rolls it back, and the application must not commit its database.

On a version 1 repository the per-file markers described on FileRepoStagedTransaction are written instead of a journal. A failure to write one is thrown in the same way, after the markers written before it have been removed again. The marker of a file that another transaction has added and not committed yet cannot be written while that transaction is open, because it holds the marker. Staging waits for such a marker as DeleteAsync(FileId, CancellationToken) does, and goes on when the adding transaction has finished, whichever way it did. If the marker is still in use when the wait is over, the method throws a RepoFileBusyException, and nothing has been staged.

Exceptions

Type	Condition
InvalidOperationException	The transaction has already been staged, or it has been rolled back.
RepoFileBusyException	On a version 1 repository, the indeterminate marker of a deleted file was still in use when the wait for it was over, which normally means that another transaction is adding the file and has not committed or rolled back yet. Nothing has been staged.
IOException	The journal (or on a version 1 repository, a marker) could not be written.
OperationCanceledException	The token was cancelled while the call waited. Nothing has been staged.