String

OpenPitStringView

Non-owning UTF-8 string view.

This type never owns memory. It borrows bytes from another object.

Lifetime contract:

• ptr points to len readable bytes;
• the memory is valid while the original object is alive and the source string has not been modified;
• the caller must not free or mutate memory behind ptr.
• if the caller needs to retain the string beyond that announced lifetime, the caller must copy the bytes.

typedef struct OpenPitStringView {
    const uint8_t * ptr;
    size_t len;
} OpenPitStringView;

OpenPitSharedString

Owning shared-string handle.

Use this type when an FFI function needs to hand a string to the caller whose lifetime must extend beyond the single FFI call and whose storage must not depend on thread-local state remaining intact on the reader side.

Ownership contract:

• every non-null *mut OpenPitSharedString returned through FFI is owned by the caller;
• the caller MUST release it with openpit_destroy_shared_string when no longer needed; failing to do so leaks the underlying allocation;
• the handle internally holds a reference-counted copy of the string, so multiple live handles pointing at the same original value are safe and independent; destroying one handle does not affect the others.

Read contract:

• read the bytes with openpit_shared_string_view;
• the returned OpenPitStringView is valid while this specific handle is alive and must not outlive the call to openpit_destroy_shared_string for this handle.

Threading contract:

• the handle itself is safe to move to and read from any thread once the caller has received it; no thread-local state is consulted when reading or destroying.

typedef struct OpenPitSharedString OpenPitSharedString;

openpit_create_shared_string

Copies a UTF-8 view into a new caller-owned shared-string handle.

Returns null only when value.ptr is null. Invalid UTF-8 bytes are replaced with the Unicode replacement character, so callback error details remain distinguishable from a missing payload. The returned handle MUST be released with openpit_destroy_shared_string. This constructor is intended for callback error channels whose payload must remain valid after the callback returns.

Safety

A non-null value.ptr must point to value.len readable bytes for the duration of this call.

OpenPitSharedString * openpit_create_shared_string(
    OpenPitStringView value
);

openpit_destroy_shared_string

Releases a OpenPitSharedString handle.

Null input is a no-op.

After this call, the handle and any OpenPitStringView previously obtained from it are invalid and must not be used.

void openpit_destroy_shared_string(
    OpenPitSharedString * handle
);

openpit_shared_string_view

Borrows a read-only view of the bytes stored in the handle.

Returns an unset view (ptr == null, len == 0) when handle is null.

The returned view is valid only while handle remains alive. The caller must copy the bytes if they must outlive the handle.

OpenPitStringView openpit_shared_string_view(
    const OpenPitSharedString * handle
);