Rationale behind the Tribler Core API

The core API is inspired by the ​libtorrent interface but makes all configurations first-class objects such that they can be independently manipulated (i.e., loaded, saved, set as default). Making configurations first- class objects requires special measures because of their dual nature. First, when the download engine or individual download has not yet started, configurations are more or less (key,value) pairs. Second, when the downloads have started the configuration represents actual parameters in the download engine, and when config parameters are changed one expects that the engine's behaviour also changes directly.

To support configs as first-class objects we therefore distinguish between startup and runtime configs. A runtime config is associated with the download engine via a Session or Download object. Changing the values of a runtime config will alter the behaviour of the download in a thread safe way.

Thread Safety

All calls to Session, Download and DownloadState are thread safe. Startup configs are not thread safe. To prevent concurrency issues, startup configs passed to a Session/Download object are first copied and the copy then becomes the runtime config. When passing an startup config as argument it may not be modified concurrently. Runtime configs are thread safe, as just mentioned. Note that changes to runtime configs (i.e., changing upload limit) are asynchronous, i.e., they will be scheduled on the network thread and thus may or may not be executed when the method returns. In the future, should the need arise, errors in changing a runtime config may be reported via a callback.

Persistence Support

We use the Python pickling mechanism to make objects persistent. We add a version number to the state before it is saved. To indicate serializability classes inherit from the Serializable interface. For a Session there is a special checkpointing mechanism.

Session Object

At the moment, we use a singleton Session, i.e., there is only one instance of the Session class in a process. Theoretically, Session can be a real class with multiple instances. For implementation purposes making it a Singleton is easier, as a lot of our internal stuff are currently singletons (e.g. databases and *MsgHandler, etc.)

Modifiability of parameters

Many configuration parameters may be modified at runtime. Some parameters may be theoretically modifiable but implementing this behaviour may be too complex. For example, changing the destination dir of a download a runtime is possible, but complex to implement. The class definitions indicate which parameters are runtime modifiable, and points of attention.

Note that some parameters should be modified with great care. For example. the listen = tracker port of a Session can be easily modified, but if the Session had been used to create new torrents that have been distributed to Web sites, you cannot simply change the listening port as it means that all torrent files out in the world become invalid.