alert masks

The output from this program will be quite verbose, which is probably a good starting point to get some understanding of what's going on. Alerts are categorized into alert categories. Each category can be enabled and disabled independently via the alert mask.

The alert mask is a configuration option offered by libtorrent. There are many configuration options, see settings_pack. The alert_mask setting is an integer of the category flags ORed together.

For instance, to only see the most pertinent alerts, the session can be constructed like this:

lt::settings_pack pack;
pack.set_int(lt::settings_pack::alert_mask
        , lt::alert::error_notification
        | lt::alert::storage_notification
        | lt::alert::status_notification);

lt::session ses(pack);

Configuration options can be updated after the session is started by calling apply_settings(). Some settings are best set before starting the session though, like listen_interfaces, to avoid race conditions. If you start the session with the default settings and then immediately change them, there will still be a window where the default settings apply.

Changing the settings may trigger listen sockets to close and re-open and NAT-PMP, UPnP updates to be sent. For this reason, it's typically a good idea to batch settings updates into a single call.

session destruction

The session destructor is blocking by default. When shutting down, trackers will need to be contacted to stop torrents and other outstanding operations need to be cancelled. Shutting down can sometimes take several seconds, primarily because of trackers that are unresponsive (and time out) and also DNS servers that are unresponsive. DNS lookups are especially difficult to abort when stalled.

In order to be able to start destruction an wait for it asynchronously, one can call session::abort().

This call returns a session_proxy object, which is a handle keeping the session state alive while destructing it. It deliberately does not provide any of the session operations, since it's shutting down.

After having a session_proxy object, the session destructor does not block. However, the session_proxy destructor will.

This can be used to shut down multiple sessions or other parts of the application in parallel.

asynchronous operations

Essentially any call to a member function of session or torrent_handle that returns a value is a blocking synchronous call. Meaning it will post a message to the main libtorrent thread and wait for a response. Such calls may be expensive, and in applications where stalls should be avoided (such as user interface threads), blocking calls should be avoided.

In the example above, session::add_torrent() returns a torrent_handle and is thus blocking. For higher efficiency, async_add_torrent() will post a message to the main thread to add a torrent, and post the resulting torrent_handle back in an alert (add_torrent_alert). This is especially useful when adding a lot of torrents in quick succession, as there's no stall in between calls.

In the example above, we don't actually use the torrent_handle for anything, so converting it to use async_add_torrent() is just a matter of replacing the add_torrent() call with async_add_torrent().

경축! 아무것도 안하여 에스천사게임즈가 새로운 모습으로 재오픈 하였습니다.
어린이용이며, 설치가 필요없는 브라우저 게임입니다.
https://s1004games.com

torrent_status_updates

To get updates to the status of torrents, call post_torrent_updates() on the session object. This will cause libtorrent to post a state_update_alert containing torrent_status objects for all torrents whose status has changed since the last call to post_torrent_updates().

The state_update_alert looks something like this:

struct state_update_alert : alert
{
        virtual std::string message() const;
        std::vector<torrent_status> status;
};

The status field only contains the torrent_status for torrents with updates since the last call. It may be empty if no torrent has updated its state. This feature is critical for scalability.

See the torrent_status object for more information on what is in there. Perhaps the most interesting fields are total_payload_download, total_payload_upload, num_peers and state.

resuming torrents

Since bittorrent downloads pieces of files in random order, it's not trivial to resume a partial download. When resuming a download, the bittorrent engine must restore the state of the downloading torrent, specifically which parts of the file(s) are downloaded. There are two approaches to doing this:

1. read every piece of the downloaded files from disk and compare it against its expected hash.
2. save to disk the state of which pieces (and partial pieces) are downloaded, and load it back in again when resuming.

If no resume data is provided with a torrent that's added, libtorrent will employ (1) by default.

To save resume data, call save_resume_data() on the torrent_handle object. This will ask libtorrent to generate the resume data and post it back in a save_resume_data_alert. If generating the resume data fails for any reason, a save_resume_data_failed_alert is posted instead.

Exactly one of those alerts will be posted for every call to save_resume_data(). This is an important property when shutting down a session with multiple torrents, every resume alert must be handled before resuming with shut down. Any torrent may fail to save resume data, so the client would need to keep a count of the outstanding resume files, decremented on either save_resume_data_alert or save_resume_data_failed_alert.

The save_resume_data_alert looks something like this:

struct save_resume_data_alert : torrent_alert
{
        virtual std::string message() const;

        // points to the resume data.
        boost::shared_ptr<entry> resume_data;
};

resume_data points to an entry object. This represents a node or a tree of nodes in a bencoded structure, which is the native encoding scheme in bittorrent. It can be encoded into a byte buffer or file using bencode().

When adding a torrent with resume data, set the add_torrent_params::resume_data to contain the bencoded buffer of the resume data.

example

Here's an updated version of the above example with the following updates:

1. not using blocking calls
2. printing torrent status updates rather than the raw log
3. saving and loading resume files

#include <iostream>
#include <thread>
#include <chrono>
#include <fstream>

#include <libtorrent/session.hpp>
#include <libtorrent/add_torrent_params.hpp>
#include <libtorrent/torrent_handle.hpp>
#include <libtorrent/alert_types.hpp>
#include <libtorrent/bencode.hpp>
#include <libtorrent/torrent_status.hpp>

namespace lt = libtorrent;
using clk = std::chrono::steady_clock;

// return the name of a torrent status enum
char const* state(lt::torrent_status::state_t s)
{
  switch(s) {
    case lt::torrent_status::checking_files: return "checking";
    case lt::torrent_status::downloading_metadata: return "dl metadata";
    case lt::torrent_status::downloading: return "downloading";
    case lt::torrent_status::finished: return "finished";
    case lt::torrent_status::seeding: return "seeding";
    case lt::torrent_status::allocating: return "allocating";
    case lt::torrent_status::checking_resume_data: return "checking resume";
    default: return "<>";
  }
}

int main(int argc, char const* argv[])
{
  if (argc != 2) {
    std::cerr << "usage: " << argv[0] << " <magnet-url>" << std::endl;
    return 1;
  }

  lt::settings_pack pack;
  pack.set_int(lt::settings_pack::alert_mask
    , lt::alert::error_notification
    | lt::alert::storage_notification
    | lt::alert::status_notification);

  lt::session ses(pack);
  lt::add_torrent_params atp;
  clk::time_point last_save_resume = clk::now();

  // load resume data from disk and pass it in as we add the magnet link
  std::ifstream ifs(".resume_file", std::ios_base::binary);
  ifs.unsetf(std::ios_base::skipws);
  atp.resume_data.assign(std::istream_iterator<char>(ifs)
    , std::istream_iterator<char>());
  atp.url = argv[1];
  atp.save_path = "."; // save in current dir
  ses.async_add_torrent(atp);

  // this is the handle we'll set once we get the notification of it being
  // added
  lt::torrent_handle h;
  for (;;) {
    std::vector<lt::alert*> alerts;
    ses.pop_alerts(&alerts);

    for (lt::alert const* a : alerts) {
      if (auto at = lt::alert_cast<lt::add_torrent_alert>(a)) {
        h = at->handle;
      }
      // if we receive the finished alert or an error, we're done
      if (lt::alert_cast<lt::torrent_finished_alert>(a)) {
        h.save_resume_data();
        goto done;
      }
      if (lt::alert_cast<lt::torrent_error_alert>(a)) {
        std::cout << a->message() << std::endl;
        goto done;
      }

      // when resume data is ready, save it
      if (auto rd = lt::alert_cast<lt::save_resume_data_alert>(a)) {
        std::ofstream of(".resume_file", std::ios_base::binary);
        of.unsetf(std::ios_base::skipws);
        lt::bencode(std::ostream_iterator<char>(of)
          , *rd->resume_data);
      }

      if (auto st = lt::alert_cast<lt::state_update_alert>(a)) {
        if (st->status.empty()) continue;

        // we only have a single torrent, so we know which one
        // the status is for
        lt::torrent_status const& s = st->status[0];
        std::cout << "\r" << state(s.state) << " "
          << (s.download_payload_rate / 1000) << " kB/s "
          << (s.total_done / 1000) << " kB ("
          << (s.progress_ppm / 10000) << "%) downloaded\x1b[K";
        std::cout.flush();
      }
    }
    std::this_thread::sleep_for(std::chrono::milliseconds(200));

    // ask the session to post a state_update_alert, to update our
    // state output for the torrent
    ses.post_torrent_updates();

    // save resume data once every 30 seconds
    if (clk::now() - last_save_resume > std::chrono::seconds(30)) {
      h.save_resume_data();
    }
  }

  // TODO: ideally we should save resume data here

done:
  std::cout << "\ndone, shutting down" << std::endl;
}

torrent files

To add torrent files to a session (as opposed to a magnet link), it must first be loaded into a torrent_info object.

The torrent_info object can be created either by filename a buffer or a bencoded structure. When adding by filename, there's a sanity check limit on the size of the file, for adding arbitrarily large torrents, load the file outside of the constructor.

The torrent_info object provides an opportunity to query information about the .torrent file as well as mutating it before adding it to the session.

bencoding

bencoded structures is the default data storage format used by bittorrent, such as .torrent files, tracker announce and scrape responses and some wire protocol extensions. libtorrent provides an efficient framework for decoding bencoded data through bdecode() function.

There are two separate mechanisms for encoding and decoding. When decoding, use the bdecode() function that returns a bdecode_node. When encoding, use bencode() taking an entry object.

The key property of bdecode() is that it does not copy any data out of the buffer that was parsed. It builds the tree structures of references pointing into the buffer. The buffer must stay alive and valid for as long as the bdecode_node is in use.

For performance details on bdecode(), see the blog post about it.