# Libtorrent Notes

## Alerts

Alerts are key aspect of libtorrent. They are used for:

1. **Signaling relevant events.** Things like when a torrent gets added, deleted, or certain error conditions, will be signaled as events.
2. **Asynchronous responses.** The way to consume replies from asynchronous calls is by means of alerts. For instance, `post_dht_stats` will generate a `dht_stats` event.
3. **Debug events.** Libtorrent can be compiled with various logging options enabled. These logging options will not generate logs in the sense one would expect, i.e., messages to stdout/stderr. They will instead generate alerts which can then be consumed from the same alert queue as everything else.

## Alert Categories

Libtorrent allows clients to define which alerts they want to receive by calling [apply_settings](https://github.com/arvidn/libtorrent/blob/bed9075288d6431a92b83cac0a07a3832150dfcd/include/libtorrent/session_handle.hpp#L850) with an alert mask which is the bitwise or of the _alert categories_ the client is interest in. This begs the question:

1. what are the alert categories;
2. how do alerts map onto those.

Alert categories are declared in [alert.hpp](https://github.com/arvidn/libtorrent/blob/RC_2_0/include/libtorrent/alert.hpp#L78). The actual alert declarations are in [alert_types.hpp](https://github.com/arvidn/libtorrent/blob/RC_2_0/include/libtorrent/alert_types.hpp). Each alert declaration has a form like:

struct TORRENT_EXPORT i2p_alert final : alert
{
  // internal
  TORRENT_UNEXPORT i2p_alert(aux::stack_allocator& alloc, error_code const& ec);

  TORRENT_DEFINE_ALERT(i2p_alert, 77)

  static constexpr alert_category_t static_category = alert_category::error;
  std::string message() const override;

  // the error that occurred in the i2p SAM connection
  error_code error;
};

the `static_category` defines the cateogry for this particular alert. Some alerts do not have a category defined, which :

struct TORRENT_EXPORT session_stats_header_alert final : alert
{
  // internal
  explicit TORRENT_UNEXPORT session_stats_header_alert(aux::stack_allocator& alloc);
  TORRENT_DEFINE_ALERT(session_stats_header_alert, 92)

  static constexpr alert_category_t static_category = {};
  std::string message() const override;
};