dksdk_ffi_c/cls_capnp_segment.h¶

Defines

DK_IIDSTR_CAPN_SEGMENT¶

The interface identifier for the Cap 'n Segment dk_cls_capnp_segment.

The Cap 'n Proto Segment is an allocated Cap'n Proto segment that is managed by the host language (C).

DK_CLSIDSTR_CAPN_SEGMENT¶

The class identifier for the Cap 'n Proto Segment.

The Cap 'n Proto Segment is an allocated Cap'n Proto segment that is managed by the host language (C).

When queried with dksdk_ffi_registry_get the class identifier will give a struct dksdk_ffi_i_com. Use one of the interfaces in the next section to get additional fields and methods.

_DK_CLS_CAPN_SEGMENT_COPYSZ()¶

Internal.

At least the size of a struct(copy) in capn.c's copy_ptr function.

_DK_CLS_CAPN_SEGMENT_NEW_CAPN_SEGMENT_HELPER(CAPN, CAPN_SEGMENT, SZ, FORCE)¶

Internal.

Enums

enum dksdk_ffi_c_cls_capn_segment_choice¶

Tells the allocator whether to choose heap or stack allocation, or force either heap or stack.

The typical use case is when you are returning a Cap n' Proto message to the caller. You can pre-allocate space for the return value on the stack, and if it spills over, the remainder of the message can be malloc'd. This is done automatically when you use segment_best_alloc with somewhat opaque logic.

However, when you know you must disable the stack or heap you can use segment_force_heap or segment_force_stack, respectively.

Values:

enumerator segment_best_alloc¶

enumerator segment_force_heap¶

enumerator segment_force_stack¶

Functions

int dk_cls_capnp_segment_new(struct dksdk_ffi *ffi, struct dk_cls_capnp_segment **ppObject, size_t size)¶

Allocates a segment and creates a dk_cls_capnp_segment around the allocated segment.

Parameters:

• ffi -- [in] The FFI pointer from dksdk_ffi_host_create

• ppObject -- [inout] The address of the pointer to an object initialized with zero bytes. On success the object will be populated. The object must be released when the caller is finished with it. On failure the de-referenced address *ppObject will be NULL.

• size -- [in] The minimum number of bytes to allocate. Must be at least one byte or greater.

Returns:

• DKSDK_FFI_OK on success

• DKSDK_FFI_ERR_INVALID_STATE when there is no memory

• DKSDK_FFI_ERR_INVALID_ARGUMENT when ffi or ppObject is NULL

int dk_cls_capnp_segment_move(struct dksdk_ffi *ffi, void *externalSegment, struct dk_cls_capnp_segment **ppObject, void *externalSegmentFreeableOpt, void (*externalSegmentFreeOpt)(void*))¶

Creates a dk_cls_capnp_segment from an externally malloc'd segment.

The external segment will be free'd when the dk_cls_capnp_segment reference count goes to zero.

Do NOT use the external segment except through the dk_cls_capnp_segment. This function moves ownership from the caller into dk_cls_capnp_segment.

Parameters:

• ffi -- [in] The FFI pointer from dksdk_ffi_host_create

• externalSegment -- [in] The external segment

• ppObject -- [inout] The address of the pointer to an object initialized with zero bytes. On success the object will be populated. The object must be released when the caller is finished with it. On failure the de-referenced address *ppObject will be NULL.

• externalSegmentFreeableOpt -- [in] The memory associated with externalSegment that should be freed when dk_cls_capnp_segment reference count goes to zero. May be NULL if no memory should be freed (ex. stack allocated).

• externalSegmentFreeOpt -- [in] A free function for the segmentFreeable, or NULL if the externalSegmentFreeableOpt is not meant to be freed (ex. stack allocated).

Returns:

• DKSDK_FFI_OK on success

• DKSDK_FFI_ERR_INVALID_STATE when there is no memory

• DKSDK_FFI_ERR_INVALID_ARGUMENT when ffi, ppObject or externalSegment is NULL

DKSDK_FFI_C_EXPORT void dk_cls_capn_init_alloc(struct dksdk_ffi *ffi, struct capn *c)¶

Initialize the Cap n' Proto message using the host allocators from DkSDK FFI.

The message is not interchangable with capn_init_malloc(). Use dk_cls_capn_segment_free_all_except_stack_allocated_segments to free the segments.

Parameters:

• ffi -- [in] The FFI pointer from dksdk_ffi_host_create

• c -- [inout] On success will be a valid Cap n' Proto message

DKSDK_FFI_C_EXPORT void dk_cls_capn_segment_free_all_except_stack_allocated_segments(struct capn *c)¶

Free all segments except those that were stack allocated; replaces capn_free safely.

A stack allocated block of memory should never be freed. Freeing is automatic, and manually freeing will likely cause segment faults.

void dk_cls_capn_segment_reset_copy_except_stack_allocated_segments(struct capn *c)¶

Remove all copy segments except those that were stack allocated.

See dk_cls_capn_segment_free_all_except_stack_allocated_segments

Variables

const dksdk_ffi_uuid DK_IID_CAPN_SEGMENT¶