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( )`

Starts the swarm.

$torrent->start();

This method triggers DHT lookups, tracker announces, and local peer discovery. It transitions the swarm to the STARTING or METADATA state.

`stop( )`

Stops the swarm.

$torrent->stop();

This method stops network activity, disconnects peers, and flushes storage.

`pause( )`

Pauses the swarm.

$torrent->pause();

This method keeps connections alive but stops data transfer.

`resume( )`

Resumes a paused swarm.

$torrent->resume();

This method resumes data transfer on existing connections.

`on( $event, $callback )`

Registers a callback for swarm events.

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

This method allows listening for events specific to this torrent.

Expected parameters:

$event: The name of the event to listen for. Supported events: piece_verified, piece_failed, status_update, peer_discovered, started, stopped, paused, resumed.
$callback: The code reference to execute when the event is emitted.

`name( )`

Returns a human-readable name for the torrent.

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

This method returns the name from the metadata if available, or a hex infohash as a fallback.

`progress( )`

Returns the download completion percentage.

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

This method returns a floating-point number between 0.0 and 100.0 representing the completion status.

`is_finished( )`

Checks if the download is complete.

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

This method returns true if the download is 100% complete and verified.

`is_seed( )`

Checks if the client is seeding.

if ($torrent->is_seed) { ... }

This method returns true if the client has all pieces and is acting as a seeder.

`is_metadata_complete( )`

Checks if metadata is loaded.

if ($torrent->is_metadata_complete) { ... }

This method returns true if the info dictionary is available.

`is_running( )`

Checks if the swarm is active.

if ($torrent->is_running) { ... }

This method returns true if the state is STARTING, RUNNING, or METADATA.

`primary_pieces_root( )`

Returns the pieces root for the first file (v2).

my $root = $torrent->primary_pieces_root();

This method returns the SHA-256 Merkle tree root for the primary file in a BitTorrent v2 torrent.

`set_piece_priority( $index, $priority )`

Sets the priority for a specific piece.

$torrent->set_piece_priority( 5, 0 );

This method allows adjusting the download priority of individual pieces. A priority of 0 means the piece will not be downloaded.

Expected parameters:

$index: The zero-based piece index.
$priority: The priority level (0 = do not download, 1 = normal, higher values = higher priority).

`set_picking_strategy( $strategy )`

Sets the piece picking algorithm.

$torrent->set_picking_strategy(PICK_SEQUENTIAL);

This method changes how the client selects pieces to download. Available strategies are defined in Net::BitTorrent::Types.

Expected parameters:

$strategy: The strategy constant to use (e.g., PICK_RAREST_FIRST, PICK_SEQUENTIAL).

`infohash_v1( )`

Returns the v1 infohash.

my $ih = $torrent->infohash_v1;

This method returns the 20-byte binary SHA-1 infohash for BitTorrent v1. Returns undef if not available.

`infohash_v2( )`

Returns the v2 infohash.

my $ih = $torrent->infohash_v2;

This method returns the 32-byte binary SHA-256 infohash for BitTorrent v2. Returns undef if not available.

`files( )`

Returns a list of file paths.

my $paths = $torrent->files;

This method returns an array reference containing the absolute paths of all files in the torrent.

`discovered_peers( )`

Returns a list of known peers.

my $peers = $torrent->discovered_peers;

This method returns an array reference of peer structures discovered via various mechanisms.

`dump_state( )`

Exports the torrent state.

my $state = $torrent->dump_state;

This method returns a data structure representing the current state of the torrent, suitable for persistence.

`load_state( $state )`

Restores the torrent state.

$torrent->load_state($state);

This method restores the torrent state from a previously dumped structure.

Expected parameters:

$state: The state data structure (hash reference).

`get_superseed_piece( $peer )`

Retrieves a piece index for super-seeding.

my $idx = $torrent->get_superseed_piece($peer);

This method selects a piece to offer to a peer when in super-seeding mode (BEP 16).

Expected parameters:

$peer: The Net::BitTorrent::Peer object.

`metadata_received_count( )`

Returns the number of metadata bytes received.

my $count = $torrent->metadata_received_count();

This method returns the total number of bytes of the info dictionary currently received.

`set_limit_up( $val )`

Sets the upload rate limit for this torrent.

$torrent->set_limit_up( 512 * 1024 );

This method sets the maximum upload rate in bytes per second for this specific swarm.

Expected parameters:

$val: The limit in bytes per second. Use 0 for unlimited.

`set_limit_down( $val )`

Sets the download rate limit for this torrent.

$torrent->set_limit_down( 1024 * 1024 );

This method sets the maximum download rate in bytes per second for this specific swarm.

Expected parameters:

$val: The limit in bytes per second. Use 0 for unlimited.

`can_read( $amount )`

Checks if a download amount is allowed by rate limits.

my $allowed = $torrent->can_read( 16384 );

This method checks both global and per-torrent rate limits and returns the amount that can be consumed.

Expected parameters:

$amount: The requested number of bytes to download.

`can_write( $amount )`

Checks if an upload amount is allowed by rate limits.

my $allowed = $torrent->can_write( 16384 );

This method checks both global and per-torrent rate limits and returns the amount that can be consumed.

Expected parameters:

$amount: The requested number of bytes to upload.

`tick( [$delta] )`

Performs periodic maintenance for the swarm.

$torrent->tick( 0.1 );

This method handles peer connections, piece requests, choking logic, and tracker announces for this swarm.

Expected parameters:

$delta - optional: The time elapsed since the last tick in seconds. Defaults to 0.1.

`add_peer( $peer )`

Adds a discovered peer to the swarm.

$torrent->add_peer({ ip => '1.2.3.4', port => 6881 });

This method adds a peer to the list of potential connections.

Expected parameters:

$peer: A hash reference or object containing ip and port.

`add_dht_nodes( $nodes )`

Adds DHT nodes to the search frontier.

$torrent->add_dht_nodes( $nodes_list );

This method adds nodes discovered via the DHT to the search frontier for this torrent.

Expected parameters:

$nodes: An array reference of node structures.

`ban_peer( $ip, $port )`

Bans a peer from the swarm.

$torrent->ban_peer( '1.2.3.4', 6881 );

This method removes a peer and prevents reconnection for a period of time.

Expected parameters:

$ip: The IP address of the peer.
$port: The port number of the peer.

`register_peer_object( $peer_obj )`

Registers an active peer connection.

$torrent->register_peer_object( $peer );

This method registers a Net::BitTorrent::Peer object as an active connection for this swarm.

Expected parameters:

$peer_obj: The Net::BitTorrent::Peer object.

`start_dht_lookup( )`

Manually triggers a DHT lookup for peers.

$torrent->start_dht_lookup();

This method initiates an iterative DHT search for peers on all supported infohashes.

`peer_id( )`

Returns the local peer ID used for this torrent.

my $id = $torrent->peer_id();

This method returns the 20-byte binary peer ID.

`trackers( )`

Returns the list of trackers.

my $trackers = $torrent->trackers();

This method returns an array reference of Net::BitTorrent::Tracker::Base objects.

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

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

To install Net::BitTorrent, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::BitTorrent

CPAN shell

perl -MCPAN -e shell
install Net::BitTorrent

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Lifecycle States:

METHODS

start( )

stop( )

pause( )

resume( )

on( $event, $callback )

name( )

progress( )

is_finished( )

is_seed( )

is_metadata_complete( )

is_running( )

primary_pieces_root( )

set_piece_priority( $index, $priority )

set_picking_strategy( $strategy )

infohash_v1( )

infohash_v2( )

files( )

discovered_peers( )

dump_state( )

load_state( $state )

get_superseed_piece( $peer )

metadata_received_count( )

set_limit_up( $val )

set_limit_down( $val )

can_read( $amount )

can_write( $amount )

tick( [$delta] )

add_peer( $peer )

add_dht_nodes( $nodes )

ban_peer( $ip, $port )

register_peer_object( $peer_obj )

start_dht_lookup( )

peer_id( )

trackers( )

Specifications

AUTHOR

COPYRIGHT

Module Install Instructions

`start( )`

`stop( )`

`pause( )`

`resume( )`

`on( $event, $callback )`

`name( )`

`progress( )`

`is_finished( )`

`is_seed( )`

`is_metadata_complete( )`

`is_running( )`

`primary_pieces_root( )`

`set_piece_priority( $index, $priority )`

`set_picking_strategy( $strategy )`

`infohash_v1( )`

`infohash_v2( )`

`files( )`

`discovered_peers( )`

`dump_state( )`

`load_state( $state )`

`get_superseed_piece( $peer )`

`metadata_received_count( )`

`set_limit_up( $val )`

`set_limit_down( $val )`

`can_read( $amount )`

`can_write( $amount )`

`tick( [$delta] )`

`add_peer( $peer )`

`add_dht_nodes( $nodes )`

`ban_peer( $ip, $port )`

`register_peer_object( $peer_obj )`

`start_dht_lookup( )`

`peer_id( )`

`trackers( )`