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 the tskit 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:

  1. Developing a new performance-oriented application.
  2. 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.