Contract of MarkNotComplete (and MarkComplete) in PieceImpl

[mahesh-hegde]

First of all thanks for the open source project.

I am writing a storage back-end (for not completely rational reasons).

I see in PieceImpl interface

// Called when the client believes the piece data will pass a hash check.
// The storage can move or mark the piece data as read-only as it sees
// fit.
MarkComplete() error
MarkNotComplete() error

What's the contract of MarkNotComplete?

Once a PieceImpl instance is marked as incomplete using MarkIncomplete will its ReaderAt/WriterAt methods be used again?

In my understanding, MarkNotComplete is only failed when hashing fails. is there other scenarios I should consider?

---

Same question for the semantics of MarkComplete(), once its called, might the same instance of PieceImpl be used for reading, or a new PieceImpl for same pieceKey is requested from TorrentImpl?

Thanks

[anacrolix]

What's the contract of MarkNotComplete?

It's called when the piece is known to not be complete. That is it's either missing or failed a piece check.

Once a PieceImpl instance is marked as incomplete using MarkIncomplete will its ReaderAt/WriterAt methods be used again?

Yes, ReaderAt is used in the piece hashing when all the chunks have been downloaded again. WriterAt is used to write them to storage.

In my understanding, MarkNotComplete is only failed when hashing fails. is there other scenarios I should consider?

A Reader attempted to read the data in the piece and got an unexpected EOF.

Same question for the semantics of MarkComplete(), once its called, might the same instance of PieceImpl be used for reading, or a new PieceImpl for same pieceKey is requested from TorrentImpl?

I don't believe so. PieceImpls are always generated on demand from the TorrentImpl. You should not store any long term state in those PieceImpls. I think TorrentImpl is generated once when a torrent is opened and the info obtained.

torrent/torrent.go

Line 92 in 56002f9

storage *storage.Torrent

.

Thanks for the great questions. If you want to do a PR to add any documentation for this, feel free.

[mahesh-hegde]

Thanks for the answer. I will be getting a bunch of more questions on storage backend if I go through this project in coming weekends!