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.
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.
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.
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.