Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix docs #432

Merged
merged 1 commit into from
Nov 13, 2024
Merged

fix docs #432

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
169 changes: 141 additions & 28 deletions demes/src/ffi.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,10 @@ pub enum SizeFunction {

/// Allocate a [`FFIError`]
///
/// # Return
///
/// * A newly-allocated [`FFIError`]
///
/// # Notes
///
/// The memory for this type is allocated via the rust allocator.
Expand Down Expand Up @@ -121,6 +125,10 @@ pub extern "C" fn demes_error_clear(error: &mut FFIError) {

/// Obtain a C string containing the error message.
///
/// # Parameters
///
/// * `errror` - an instance of [`FFIError`]
///
/// # Returns
///
/// * The error message, if one exists .
Expand All @@ -140,6 +148,10 @@ pub extern "C" fn demes_error_message(error: &FFIError) -> *mut c_char {

/// Free the memory for a [`FFIError`]
///
/// # Parameters
///
/// * `error` - mutable pointer to [`FFIError`]
///
/// # Safety
///
/// * `error` must point to a non-NULL instance of [`FFIError`]
Expand All @@ -153,6 +165,11 @@ pub unsafe extern "C" fn demes_error_deallocate(error: *mut FFIError) {

/// Free the memory for a C-style string that was allocated by this module.
///
/// # Parameters
///
/// * `ptr` - Pointer to a C-style string that has been allocated by other
/// functions from this module.
///
/// # Safety
///
/// * `ptr` must not be NULL.
Expand Down Expand Up @@ -216,14 +233,20 @@ unsafe fn load(file: std::fs::File, error: &mut FFIError, output: *mut *mut Grap

/// Generate a copy of a [`Graph`] with time units changed to generations.
///
/// # Paramters
///
/// * `graph` - the input [`Graph`]
/// * `error` - a mutable [`FFIError`]
/// * `output` - pointer to memory to store the output.
///
/// # Returns
///
/// * 0 upon success
/// * non-zero upon error
///
/// # Safety
///
/// * `output` must point to a mutable pointer to a [`Graph`]
/// * `output` must not be a null pointer.
///
/// # Side effects
///
Expand Down Expand Up @@ -351,13 +374,29 @@ pub unsafe extern "C" fn demes_graph_deallocate(graph: *mut Graph) {

/// Initialize a [`Graph`] from a YAML string.
///
/// # Parameters
///
/// * `yaml` - C-style string referring to YAML input.
/// * `graph` - a mutable pointer to a pointer to a [`Graph`].
/// * `error` - a mutatble reference/pointer to [`FFIError`].
///
/// # Returns
///
/// * An initialized [`Graph`] upon success.
/// * A null pointer upon error
/// * A null pointer if `error` contains an error state,
/// implying either an error has not been handled and/or
/// it has not been cleared.
/// * 0 upon success
/// * non-zero upon error
///
/// # Side effects
///
/// Upon success:
///
/// * The pointee of `graph` points to a newly-allocated [`Graph`].
/// This object must be freed via [`demes_graph_deallocate`].
///
/// Upon error:
///
/// * `error` will contain an error state.
/// See [`demes_error_message`].
/// * The pointee of `graph` will be a null pointer.
///
/// # Error
///
Expand All @@ -366,16 +405,16 @@ pub unsafe extern "C" fn demes_graph_deallocate(graph: *mut Graph) {
///
/// # Safety
///
/// * `yaml` must be a non-null `char *`.
/// * `yaml` must be a non-null pointer.
/// * For `yaml`, all safety requirements of
/// [`CStr::from_ptr`](std::ffi::CStr::from_ptr)
/// must be upheld.
/// * `error` must be a non-null pointer to a [`FFIError`]
/// * `graph` must not be NULL.
///
/// # Note
/// # Notes
///
/// The return value, if not NULL, **must** be freed via
/// [`demes_graph_deallocate`], else a memory leak will occur.
/// * Resource leaks may occur if the pointee of `graph` is not NULL.
#[no_mangle]
pub unsafe extern "C" fn demes_graph_load_from_yaml(
// NOTE: it is very hard to test invalid c style strings.
Expand Down Expand Up @@ -404,13 +443,29 @@ pub unsafe extern "C" fn demes_graph_load_from_yaml(

/// Initialize a [`Graph`] from a file.
///
/// # Parameters
///
/// * `filename` - C-style string referring to a file containing YAML data.
/// * `graph` - a mutable pointer to a pointer to a [`Graph`].
/// * `error` - a mutatble reference/pointer to [`FFIError`].
///
/// # Returns
///
/// * An initialized [`Graph`] upon success.
/// * A null pointer upon error
/// * A null pointer if `error` contains an error state,
/// implying either an error has not been handled and/or
/// it has not been cleared.
/// * 0 upon success
/// * non-zero upon error
///
/// # Side effects
///
/// Upon success:
///
/// * The pointee of `graph` points to a newly-allocated [`Graph`].
/// This object must be freed via [`demes_graph_deallocate`].
///
/// Upon error:
///
/// * `error` will contain an error state.
/// See [`demes_error_message`].
/// * The pointee of `graph` will be a null pointer.
///
/// # Error
///
Expand All @@ -424,11 +479,11 @@ pub unsafe extern "C" fn demes_graph_load_from_yaml(
/// [`CStr::from_ptr`](std::ffi::CStr::from_ptr)
/// must be upheld.
/// * `error` must be a non-null pointer to a [`FFIError`]
/// * `graph` must not be NULL.
///
/// # Note
/// # Notes
///
/// The return value, if not NULL, **must** be freed via
/// [`demes_graph_deallocate`], else a memory leak will occur.
/// * Resource leaks may occur if the pointee of `graph` is not NULL.
#[no_mangle]
pub unsafe extern "C" fn demes_graph_load_from_file(
// NOTE: it is very hard to test invalid c style strings.
Expand Down Expand Up @@ -973,6 +1028,10 @@ pub extern "C" fn demes_pulse_time(pulse: &Pulse) -> f64 {

/// Get a pointer to all ancestry proportions for a [`Pulse`].
///
/// # Parameters
///
/// * `pulse` - a [Pulse]
///
/// # Notes
///
/// * The return value points to memory managed by rust
Expand All @@ -987,6 +1046,10 @@ pub extern "C" fn demes_pulse_proportions(pulse: &Pulse) -> *const f64 {

/// Allocate a [`DemeIterator`].
///
/// # Parameters
///
/// * `graph` - the parent [`Graph`]
///
/// # Notes
///
/// * You must call [`demes_deme_iterator_deallocate`] to return resources
Expand All @@ -998,6 +1061,10 @@ pub extern "C" fn demes_graph_deme_iterator(graph: &Graph) -> *mut DemeIterator

/// Dellocate a [`DemeIterator`].
///
/// # Parameters
///
/// * `ptr` - pointer to [DemeIterator] to deallocate
///
/// # Safety
///
/// * `ptr` must point to a non-NULL instance of [`DemeIterator`]
Expand All @@ -1009,17 +1076,25 @@ pub unsafe extern "C" fn demes_deme_iterator_deallocate(ptr: *mut DemeIterator)

/// Advance a [`DemeIterator`]
///
/// # Parameters
///
/// * `iterator` - the [DemeIterator] to advance
///
/// # Return
///
/// * A const pointer to a [`Deme`] if the iterator is still valid.
/// * A NULL pointer when iteration has ended.
#[no_mangle]
pub extern "C" fn demes_deme_iterator_next(deme_iterator: &mut DemeIterator) -> *const Deme {
deme_iterator.next().unwrap_or(std::ptr::null())
pub extern "C" fn demes_deme_iterator_next(iterator: &mut DemeIterator) -> *const Deme {
iterator.next().unwrap_or(std::ptr::null())
}

/// Allocate and initialize an [`EpochIterator`].
///
/// # Parameters
///
/// * `deme` - the [Deme] containing the [Epoch]s for iteration
///
/// # Note
///
/// The return value must be freed using [`demes_epoch_iterator_deallocate`]
Expand All @@ -1030,17 +1105,25 @@ pub extern "C" fn demes_deme_epoch_iterator(deme: &Deme) -> *mut EpochIterator {

/// Advance an [`EpochIterator`].
///
/// # Parameters
///
/// * `iterator` - the [EpochIterator] to advance
///
/// # Return
///
/// * A const pointer to an [`Epoch`] if the iterator is still valid
/// * A NULL pointer when iteration has ended.
#[no_mangle]
pub extern "C" fn demes_epoch_iterator_next(epoch_iterator: &mut EpochIterator) -> *const Epoch {
epoch_iterator.next().unwrap_or(std::ptr::null())
pub extern "C" fn demes_epoch_iterator_next(iterator: &mut EpochIterator) -> *const Epoch {
iterator.next().unwrap_or(std::ptr::null())
}

/// Deallocate an [`EpochIterator`]
///
/// # Parameters
///
/// * `ptr` - pointer to [EpochIterator] to deallocate
///
/// # Safety
///
/// * `ptr` must be non-NULL
Expand All @@ -1063,17 +1146,25 @@ pub extern "C" fn demes_graph_pulse_iterator(graph: &Graph) -> *mut PulseIterato

/// Advance a [`PulseIterator`].
///
/// # Parameters
///
/// * `iterator` - the [PulseIterator] to advance.
///
/// # Return
///
/// * A const pointer to a [`Pulse`] if the iterator is still valid
/// * A NULL pointer when iteration has ended.
#[no_mangle]
pub extern "C" fn demes_pulse_iterator_next(pulse_iterator: &mut PulseIterator) -> *const Pulse {
pulse_iterator.next().unwrap_or(std::ptr::null())
pub extern "C" fn demes_pulse_iterator_next(iterator: &mut PulseIterator) -> *const Pulse {
iterator.next().unwrap_or(std::ptr::null())
}

/// Deallocate an [`PulseIterator`]
///
/// # Parameters
///
/// * `ptr` - pointer to [PulseIterator].
///
/// # Safety
///
/// * `ptr` must be non-NULL
Expand All @@ -1085,6 +1176,14 @@ pub unsafe extern "C" fn demes_pulse_iterator_deallocate(ptr: *mut PulseIterator

/// Allocate and initialize an [`AsymmetricMigrationIterator`].
///
/// # Parameters
///
/// * `graph` - the parent [`Graph`]
///
/// # Returns
///
/// * A newly-allocated [`AsymmetricMigrationIterator`]
///
/// # Notes
///
/// * You must call [`demes_asymmetric_migration_iterator_deallocate`] to return resources
Expand All @@ -1098,21 +1197,27 @@ pub extern "C" fn demes_graph_asymmetric_migration_iterator(

/// Advance an [`AsymmetricMigrationIterator`].
///
/// # Parameters
///
/// * `iterator` - mutable [`AsymmetricMigrationIterator`]
///
/// # Return
///
/// * A const pointer to an [`AsymmetricMigration`] if the iterator is still valid
/// * A NULL pointer when iteration has ended.
#[no_mangle]
pub extern "C" fn demes_asymmetric_migration_iterator_next(
asymmetric_migration_iterator: &mut AsymmetricMigrationIterator,
iterator: &mut AsymmetricMigrationIterator,
) -> *const AsymmetricMigration {
asymmetric_migration_iterator
.next()
.unwrap_or(std::ptr::null())
iterator.next().unwrap_or(std::ptr::null())
}

/// Deallocate an [`AsymmetricMigrationIterator`]
///
/// # Parameters
///
/// * `ptr` - pointer to [`AsymmetricMigrationIterator`]
///
/// # Safety
///
/// * `ptr` must be non-NULL
Expand Down Expand Up @@ -1155,6 +1260,10 @@ pub unsafe extern "C" fn demes_deme_ancestor_iterator(

/// Advance a [`DemeAncestorIterator`].
///
/// # Parameters
///
/// * `iterator` - mutable [`DemeAncestorIterator`]
///
/// # Return
///
/// * A const pointer to a [`DemeAncestor`] if the iterator is still valid
Expand All @@ -1168,6 +1277,10 @@ pub extern "C" fn demes_deme_ancestor_iterator_next(

/// Deallocate a [`DemeAncestorIterator`]
///
/// # Parameter
///
/// * `ptr` - pointer to [`DemeAncestorIterator`]
///
/// # Safety
///
/// * `ptr` must be non-NULL
Expand Down
Loading