github.com/anacrolix/torrent@v1.61.0/storage/interface.go (about)

     1  package storage
     2  
     3  import (
     4  	"context"
     5  	"io"
     6  
     7  	g "github.com/anacrolix/generics"
     8  
     9  	"github.com/anacrolix/torrent/metainfo"
    10  )
    11  
    12  type ClientImplCloser interface {
    13  	ClientImpl
    14  	Close() error
    15  }
    16  
    17  // Represents data storage for an unspecified torrent.
    18  type ClientImpl interface {
    19  	OpenTorrent(ctx context.Context, info *metainfo.Info, infoHash metainfo.Hash) (TorrentImpl, error)
    20  }
    21  
    22  // Returning a negative cap, can we indicate there's no specific cap? If this is not-nil we use it
    23  // as a key into piece request order. The capped bool also needs to be true to be truly capped
    24  // though.
    25  type TorrentCapacity *func() (cap int64, capped bool)
    26  
    27  // Data storage bound to a torrent.
    28  type TorrentImpl struct {
    29  	// v2 infos might not have the piece hash available even if we have the info. The
    30  	// metainfo.Piece.Hash method was removed to enforce this.
    31  	Piece func(p metainfo.Piece) PieceImpl
    32  	// Preferred over PieceWithHash. Called with the piece hash if it's available.
    33  	PieceWithHash func(p metainfo.Piece, pieceHash g.Option[[]byte]) PieceImpl
    34  	Close         func() error
    35  	// Storages that share the same space, will provide equal pointers. The function is called once
    36  	// to determine the storage for torrents sharing the same function pointer, and mutated in
    37  	// place.
    38  	Capacity TorrentCapacity
    39  
    40  	NewReader      func() TorrentReader
    41  	NewPieceReader func(p Piece) PieceReader
    42  }
    43  
    44  // Interacts with torrent piece data. Optional interfaces to implement include://
    45  //
    46  //		io.WriterTo, such as when a piece supports a more efficient way to write out incomplete chunks.
    47  //		SelfHashing, such as when a piece supports a more efficient way to hash its contents.
    48  //	 	PieceReaderer when it has a stateful Reader interface that is more efficient.
    49  type PieceImpl interface {
    50  	// These interfaces are not as strict as normally required. They can
    51  	// assume that the parameters are appropriate for the dimensions of the
    52  	// piece.
    53  	io.ReaderAt
    54  	io.WriterAt
    55  	// Called when the client believes the piece data will pass a hash check.
    56  	// The storage can move or mark the piece data as read-only as it sees
    57  	// fit.
    58  	MarkComplete() error
    59  	MarkNotComplete() error
    60  	// Returns the state of a piece. Typically, this is implemented in some kind of storage to avoid
    61  	// rehashing, and cheap checks are performed here. (The implementation maintains a cache in
    62  	// Torrent).
    63  	Completion() Completion
    64  }
    65  
    66  // Completion state of a piece.
    67  type Completion struct {
    68  	Err error
    69  	// The state is known or cached.
    70  	Ok bool
    71  	// If Ok, whether the data is correct. TODO: Check all callsites test Ok first.
    72  	Complete bool
    73  }
    74  
    75  // Allows a storage backend to override hashing (i.e. if it can do it more efficiently than the
    76  // torrent client can).
    77  type SelfHashing interface {
    78  	SelfHash() (metainfo.Hash, error)
    79  }
    80  
    81  // Piece supports dedicated reader.
    82  type PieceReaderer interface {
    83  	NewReader() (PieceReader, error)
    84  }
    85  
    86  type PieceReader interface {
    87  	io.ReaderAt
    88  	io.Closer
    89  }