REFERENCE

Lifetime

Defines how long user-provided data remains valid in relation to Solidean handles

The Lifetime enum specifies ownership and validity rules for user-provided data. It controls whether Solidean copies data immediately, requires it to remain valid until explicitly released, or extends that requirement to both direct and indirect usages. Choosing the right lifetime allows balancing memory usage, performance, and safety - with advanced modes enabling zero-copy optimizations but requiring stricter discipline from the user.

Signature

// Defines how long user-provided data remains valid in relation to Solidean handles
enum Lifetime:
    CopyImmediately = 0
    UntilDirectRelease = 1
    UntilIndirectRelease = 2

CopyImmediately

This mode ensures maximum safety by copying all provided data into Solidean's internal storage immediately. It is the simplest and safest option, allowing the caller to reuse or release buffers right after the call returns. Use CopyImmediately when memory is not a bottleneck and predictable ownership is preferred.

UntilDirectRelease

The provided data is valid until the user calls Handle::Release on all handles that are created with this data.

For example, the user can create a SurfaceBuilder referencing triangle data with UntilDirectRelease. With this, two surfaces are created and used in different meshes. These are all direct usages that the user explicitly requested. Only until after all SurfaceBuilders, Surfaces, MeshBuilders, and Meshes are Released, can the provided data safely be deleted or re-used.

Note:
if the result is an Operand, e.g. Operation::ImportFromTrianglesF32, then this applies to the Operation handle.

UntilIndirectRelease

The provided data is valid until the user calls Handle::Release on all directly or INDIRECTLY created handles.

A directly created handle is everything that the user explicitly created with this data, e.g. SurfaceBuilders, Surfaces, MeshBuilders, Meshes. An example is given in UntilDirectRelease.

Indirectly created handles are all handles that are created during an Operation that this data takes part of. For example, an Operation::Union might be able to reuse the data of an input surface for its result. If it was created with UntilIndirectRelease, then it does not have to copy the data.

This mode enables zero-copy optimization but requires careful ownership management. Incorrect use can easily lead to invalid memory access.

CAUTION: this is an advanced feature and easy to use wrongly.