Introduction
Required background.
- We assume familiarity with
tskit
. See tskit.dev. - Comfort with rust is required.
- The book is a good place to start.
- The Rustonomicon is for those who wish to dig deeper into
unsafe
rust and FFI. The 'nomicon is helpful for understanding how things like thetskit
rust API can be built in the first place.
Conventions used in this document
Here, tskit
means the rust API.
tskit-c
and tskit-python
refer to the C and Python APIs, respectively.
The phrase "data model" refers to this. This document will make little sense without an understanding of the data model.
Relation to the C API
Where necessary, we will note differences from the behavior of tskit-c
.
Much of the rust API works by calling the C API. We do not change the semantics of the C API. However, we do make stricter statements about the ownership relationships between types. For example, the C API can result in the following situation:
- A heap-allocated table collection is used to record data about the ancestry of a sample.
- That table collection is used to initialize a tree sequence. The tree sequence is told to take ownership of the tables.
This is a case where the C API requires that you respectfully no longer work with the heap-allocated table collection. To do so is undefined behavior.
The rust API forbids such situations. The creation of a tree sequence from tables consumes the tables via a move operation. Thus, any further actions on the tables is a compiler error.
This example is the kinds of differences between tskit
and tskit-c
.
Undefined behavior is (close to) impossible with tskit
.
Quick overview
Do you need tskit-rust
?
The use-cases for tskit-rust
are the same as for tskit-c
:
- Developing a new performance-oriented application.
- The input/output of this application will be a
.trees
file.
What does tskit-rust
add?
Briefly, you get the performance of C
and the strong safety guarantees of rust
.
What is tskit-rust
missing?
The crate does not cover the entire C
API.
However, client code can make direct calls to that API via the module tskit::bindings
.
Adding tskit
as a dependency to a rust project
In your Cargo.toml
:
[dependencies]
tskit = "~X.Y.Z"
The latest version to fill in X.Y.Z
can be found here.
See here for how to specify version numbers.
Feature flags.
tskit
defines several cargo features.
These are defined in the API docs.