Module demes::ffi

Define a foreign function interface (FFI) for this crate.

The FFI allows demes to be used by any language compatible with the C calling convention.

We recommend cbindgen to generate a C or C++ header file from this module.

We suggest corrosion for building using cmake.

It should be possible to use other build systems such as meson. However, we have not experimented with this. We will update this section if and when we do so.

See the c_example folder in the demes folder of this crate’s repository for a fully worked out example.

Notes

The rust API stores all strings as String, which is very different from the C pointer to std::ffi::c_char. Therefore, most functions returning * c_char return a copy of the data stored by rust. It is up to the client code to free these returned data.

Functions returning pointers all document if the return value must be freed and, if so, how to do so.

Many of the function in this module do not have an unsafe label. These labels are correct. When called from rust, these functions are indeed safe. The borrow checker prevents them from being unsafe.

However, when called from languages like C, this API is subject to the same safety pitfalls as any API for that language. Witout rust’s borrow checker, it is up to client code to make sure that parent objects (Graphs for example) are still valid when child objects (Demes for example) are passed to API functions.

Structs

• FFIError
  Opaque error type.

Enums

• SizeFunction
  The size function for an epoch.

Functions

• demes_asymmetric_migration_dest
  Get the destination deme of a AsymmetricMigration
• demes_asymmetric_migration_end_time
  Get the end time of a AsymmetricMigration
• demes_asymmetric_migration_rate
  Get the rate of a AsymmetricMigration
• demes_asymmetric_migration_source
  Get the source deme of a AsymmetricMigration
• demes_asymmetric_migration_start_time
  Get the start time of a AsymmetricMigration
• demes_c_char_deallocate^⚠
  Free the memory for a C-style string that was allocated by this module.
• demes_deme_ancestor_indexes
  Get a pointer to the indexes of all ancestors of a Deme
• demes_deme_end_size
  Get the end time of a Deme.
• demes_deme_end_time
  Get the end time of a Deme.
• demes_deme_epoch
  Get a pointer to an Epoch of a Deme.
• demes_deme_name
  Get the name of a Deme.
• demes_deme_num_ancestors
  Get the number of ancestors of a Deme.
• demes_deme_num_epochs
  Get the number of epochs in a Deme
• demes_deme_proportions
  Get the ancestry proportions of a Deme.
• demes_deme_size_at^⚠
  Get the size of a Deme at a specific time.
• demes_deme_start_size
  Get the start size of a Deme.
• demes_deme_start_time
  Get the start time of a Deme.
• demes_epoch_end_size
  Get the end size of an Epoch.
• demes_epoch_end_time
  Get the end time of an Epoch.
• demes_epoch_size_at^⚠
  Get the size of an Epoch at a specific time.
• demes_epoch_size_function
  Get the SizeFunction of an Epoch.
• demes_epoch_start_size
  Get the start size of an Epoch.
• demes_epoch_start_time
  Get the start time of an Epoch.
• demes_error_allocate
  Allocate a FFIError
• demes_error_clear
  Clear error state.
• demes_error_deallocate^⚠
  Free the memory for a FFIError
• demes_error_has_error
  Check if a FFIError contains an error state.
• demes_error_message
  Obtain a C string containing the error message.
• demes_graph_deallocate^⚠
  Free the memory for a Graph
• demes_graph_deme
  Get a pointer to a Deme from a Graph
• demes_graph_into_generations^⚠
  Generate a copy of a Graph with time units changed to generations.
• demes_graph_into_integer_generations^⚠
  Generate a copy of a Graph with all Epoch start/end times rounded to the nearest integer values.
• demes_graph_into_integer_start_end_sizes^⚠
  Generate a copy of a Graph with all Epoch start/end sizes rounded to the nearest integer values.
• demes_graph_load_from_file^⚠
  Initialize a Graph from a file.
• demes_graph_load_from_yaml^⚠
  Initialize a Graph from a YAML string.
• demes_graph_migration
  Get a pointer to an AsymmetricMigration from a Graph
• demes_graph_num_demes
  Get the number of demes in a Graph
• demes_graph_num_migrations
  Get the number of AsymmetricMigration items in a Graph.
• demes_graph_num_pulses
  Get the number of Pulse items in a Graph.
• demes_graph_pulse
  Get a pointer to an Pulse from a Graph
• demes_graph_to_yaml^⚠
  Return a string representation of the Graph
• demes_graph_toplevel_metadata_json^⚠
  Return a string representation of the Graph’s toplevel metadata in JSON format
• demes_graph_toplevel_metadata_yaml^⚠
  Return a string representation of the Graph’s toplevel metadata in YAML format
• demes_pulse_num_sources
  Get the number of source demes of a Pulse.
• demes_pulse_proportions
  Get a pointer to all ancestry proportions for a Pulse.
• demes_pulse_source
  Get the source deme of a Pulse.
• demes_pulse_time
  Get the time of a Pulse.