/ 
Net-BitTorrent-v2.0.0-20260209033804-TRIAL
/ Net::BitTorrent::Torrent

NAME

Net::BitTorrent::Torrent - High-level Torrent/Swarm Manager

SYNOPSIS

my $torrent = $client->add_magnet( $uri, './downloads');

# Monitor progress
$torrent->on( piece_verified => sub ($t, $index) {
    printf "[%s] Progress: %.2f%%\n", $t->name, $t->progress;
});

# Wait for metadata (if magnet)
$torrent->on( status_update => sub ($t, $stats) {
    if ($t->is_metadata_complete) {
        say "Metadata received for " . $t->name;
        # Torrent will automatically transition state if start() was called
    }
});

# Example: Acting as a partial seeder
$torrent->on( started => sub ($t) {
    if ($t->is_seed) {
        say "Initial seeding complete, continuing to share...";
    }
});

$torrent->start( );

DESCRIPTION

Net::BitTorrent::Torrent represents a single BitTorrent swarm. It orchestrates the interaction between peers, the piece picker, and the storage layer.

Lifecycle States:

  • STATE_STOPPED: No network activity.

  • STATE_METADATA: (Magnet mode) Fetching the info dictionary via BEP 09.

  • STATE_STARTING: Initializing storage and announcing to trackers.

  • STATE_RUNNING: Actively downloading and uploading data.

  • STATE_PAUSED: Connections are maintained, but no data is transferred.

METHODS

start() / stop() / pause() / resume()

Controls the operational state of the swarm.

$torrent->start();
# ... later ...
$torrent->pause();

start( ) triggers DHT lookups, tracker announces, and local peer discovery.

on( $event, $callback )

Registers a callback for swarm events.

$torrent->on(piece_verified => sub ($t, $idx) { ... });

Currently emits the following events:

  • piece_verified: ($torrent, $index)

  • piece_failed: ($torrent, $index)

  • status_update: ($torrent, $stats_hash)

  • peer_discovered: ($torrent, $peer_hash)

  • started, stopped, paused, resumed: ($torrent)

name( )

Returns a human-readable name for the torrent.

say 'Downloading: ' . $torrent->name;

The name from the metadata if returned or a hex infohash as a fallback.

progress( )

Returns the download completion percentage (0.0 to 100.0).

printf 'Done: %.2f%%\r', $torrent->progress;

is_finished( )

Returns true if the download is 100% complete and verified.

say 'Download complete!' if $torrent->is_finished;

is_seed( )

Returns true if the client is currently acting as a seeder for this swarm (all pieces available).

is_metadata_complete( )

Returns true if the torrent's metadata (info dictionary) has been loaded. This is always true for .torrent files and becomes true for magnets once BEP 09 exchange completes.

is_running( )

Returns true if the swarm is in an active state (STARTING, RUNNING, or METADATA).

primary_pieces_root( )

Returns the SHA-256 pieces root for the first file in the torrent (v2 only).

set_piece_priority( $index, $priority )

Sets the weight for a specific piece.

# Skip a piece
$torrent->set_piece_priority( 5, 0 ); # $priority values: 0=skip, 1=normal, 2+=high

set_picking_strategy( $strategy )

Switch between algorithms: PICK_RAREST_FIRST, PICK_SEQUENTIAL, or PICK_STREAMING.

infohash_v1( ) / infohash_v2( )

Returns the binary infohashes for the swarm.

files( )

Returns an arrayref of absolute paths (as strings) for all files in the torrent.

discovered_peers( )

Returns a list of peers found via DHT, Trackers, PEX, and LPD.

dump_state( ) / load_state( $state )

Internal persistence methods for "save_state" in Net::BitTorrent.

Specifications

  • BEP 03: Core Peer Wire Protocol

  • BEP 06: Fast Extension

  • BEP 09: Metadata Exchange

  • BEP 11: Peer Exchange (PEX)

  • BEP 16: Super-seeding Logic

  • BEP 33: DHT Scraping

  • BEP 52: BitTorrent v2 (Hybrid support)

AUTHOR

Sanko Robinson <sanko@cpan.org>

COPYRIGHT

Copyright (C) 2008-2026 by Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.