Iterator Resources and Global Configuration

Most sequence iterators only borrow their operands and require no explicit destruction. Some operators allocate a materialized buffer or a shared hash table. Those resources must be released with the function that belongs to the constructing API.

Reset Is Not General Destruction

An iterator's installed reset callback rewinds its pipeline. It does not provide a universal destructor for every temporary resource. The public mco_seq_reset_iterator(), mco_seq_reset_unary_iterator(), and mco_seq_reset_binary_iterator() functions are standard reset implementations, primarily useful when implementing custom iterators.

Materialized Buffers

    void mco_seq_free_buffer(mco_seq_iterator_h iterator);

Call mco_seq_free_buffer() only when the constructing function allocated and attached a temporary buffer to that iterator. The operation is idempotent after such a buffer is released. Do not call it for iterators created by mco_seq_unget_TYPE(), mco_seq_unget_nullable_TYPE(), or their char variants: those functions reference application-owned storage.

Hash Aggregation State

    mco_bool mco_seq_is_hash_aggregate(mco_seq_iterator_h iterator);
    mco_bool mco_seq_free_hash(mco_seq_iterator_h iterator);
    void mco_seq_release_hash(mco_seq_iterator_h iterator);

mco_seq_is_hash_aggregate() identifies a hash-aggregation result iterator. A hash aggregate can return two iterators that share one hash state. mco_seq_free_hash() releases that shared state from either result and returns MCO_YES when state was released, or MCO_NO when it had already been released. mco_seq_release_hash() is the lower-level release operation and requires valid, unreleased hash state; prefer mco_seq_free_hash() in application cleanup code.

Allocator Callbacks

    typedef void* (*mco_seq_malloc_t)(
        mco_seq_iterator_h iterator, mco_size_t size);
    typedef void (*mco_seq_free_t)(
        mco_seq_iterator_h iterator, void* ptr, mco_size_t size);

    void mco_seq_redefine_allocator(
        mco_seq_malloc_t custom_malloc,
        mco_seq_free_t custom_free);

    void* mco_seq_sys_malloc(
        mco_seq_iterator_h iterator, mco_size_t size);
    void mco_seq_sys_free(
        mco_seq_iterator_h iterator, void* ptr, mco_size_t size);

mco_seq_sys_malloc() and mco_seq_sys_free() are the default callbacks. mco_seq_redefine_allocator() changes the process-wide callbacks stored in mco_seq_malloc and mco_seq_free. Install a matching non-NULL pair before constructing sequence pipelines, and do not change it while allocated sequence state is still active. A custom free callback must accept the same iterator and byte size that accompanied the allocation.

Binding Checks

    mco_bool mco_seq_enable_check_bindings(mco_bool enabled);
            

This process-wide switch controls additional checks that reject invalid reuse of bounded iterator operands. The function returns the previous value. The current value is also exposed as mco_seq_check_bindings. Enable or disable it during initialization rather than while pipelines are active.

Hash Table Tuning

mco_seq_hash_table_init_size and mco_seq_hash_table_load_factor are process-wide defaults used by dynamically sized hash operations. Configure them before creating hash pipelines. Values that are too small increase reallocation work; invalid or extreme values can cause allocation failures or poor performance.

Ownership Checklist

• Generated field iterators borrow the object and transaction context.
• Most result iterators borrow their operand iterators and callback contexts.
• unget iterators borrow application data and NULL bitmaps.
• Operators that materialize data may own a temporary buffer released by mco_seq_free_buffer().
• Hash aggregation results can share state released once by mco_seq_free_hash().