kcenon::container::async::async_container Class Reference

Async wrapper for value_container operations. More...

#include <async_container.h>

Collaboration diagram for kcenon::container::async::async_container:

Public Member Functions
	async_container (std::shared_ptr< value_container > container)
	Construct async_container with existing container.
	async_container ()
	Construct async_container with new empty container.
	async_container (async_container &&other) noexcept=default
	Move constructor.
async_container &	operator= (async_container &&other) noexcept=default
	Move assignment operator.
	~async_container ()=default
	Destructor.
	async_container (const async_container &)=delete
async_container &	operator= (const async_container &)=delete
std::shared_ptr< value_container >	get_container () const noexcept
	Get the underlying container.
void	set_container (std::shared_ptr< value_container > container) noexcept
	Set the underlying container.
task< std::vector< uint8_t > >	serialize_async () const
	Serialize container to byte array asynchronously.
task< std::string >	serialize_string_async () const
	Serialize container to string asynchronously.
template<typename T >
async_container &	set (std::string_view key, T &&value)
	Set a value in the container.
template<typename T >
std::optional< T >	get (std::string_view key) const
	Get a value from the container.
bool	contains (std::string_view key) const noexcept
	Check if container contains a key.
task< bool >	load_async (std::string_view path, progress_callback callback=nullptr)
	Load container from file asynchronously.
task< bool >	save_async (std::string_view path, progress_callback callback=nullptr)
	Save container to file asynchronously.
generator< std::vector< uint8_t > >	serialize_chunked (size_t chunk_size=64 *1024) const
	Serialize container in chunks using generator.

Static Public Member Functions
static task< std::shared_ptr< value_container > >	deserialize_async (std::span< const uint8_t > data)
	Deserialize from byte array asynchronously.
static task< std::shared_ptr< value_container > >	deserialize_string_async (std::string_view data)
	Deserialize from string asynchronously.
static task< std::shared_ptr< value_container > >	deserialize_streaming (std::span< const uint8_t > data, bool is_final=true)
	Deserialize container progressively from chunks.

Private Attributes
std::shared_ptr< value_container >	container_

Detailed Description

Async wrapper for value_container operations.

This class wraps a value_container and provides async versions of serialization and deserialization operations using C++20 coroutines.

The async operations offload CPU-bound work to a separate thread, allowing the calling coroutine to yield and resume when the operation completes.

Properties:

• Thread-safe wrapper for value_container
• Supports both Result-based and exception-based APIs
• Movable but not copyable

Examples

asio_integration_example.cpp, and async_coroutine_example.cpp.

Definition at line 164 of file async_container.h.

Constructor & Destructor Documentation

async_container() [1/4]

kcenon::container::async::async_container::async_container ( std::shared_ptr< value_container > container )

inlineexplicit

Construct async_container with existing container.

Parameters

container

Shared pointer to value_container

Definition at line 171 of file async_container.h.

            : container_(std::move(container))
        {
        }

async_container() [2/4]

kcenon::container::async::async_container::async_container ( )

inline

Construct async_container with new empty container.

Definition at line 179 of file async_container.h.

            : container_(std::make_shared<value_container>())
        {
        }

async_container() [3/4]

kcenon::container::async::async_container::async_container ( async_container && other )

defaultnoexcept

Move constructor.

~async_container()

kcenon::container::async::async_container::~async_container ( )

default

Destructor.

async_container() [4/4]

kcenon::container::async::async_container::async_container ( const async_container & )

delete

Member Function Documentation

contains()

bool kcenon::container::async::async_container::contains ( std::string_view key ) const

inlinenodiscardnoexcept

Check if container contains a key.

Parameters

key	Key name to check

Returns

true if key exists

Definition at line 346 of file async_container.h.

        {
            return container_->contains(key);
        }

References container_.

deserialize_async()

task< std::shared_ptr< value_container > > kcenon::container::async::async_container::deserialize_async ( std::span< const uint8_t > data )

inlinestaticnodiscard

Deserialize from byte array asynchronously.

Creates a new container from serialized data.

Parameters

data	Span of bytes containing serialized container data

Returns

task containing Result with deserialized container or error

std::vector<uint8_t> data = receive_data();
auto result = co_await async_container::deserialize_async(data);
if (result.is_ok()) {
    auto container = result.value();
    // Use deserialized container
}

Definition at line 891 of file async_container.h.

    {
        std::vector<uint8_t> data_copy(data.begin(), data.end());
        auto result = co_await detail::make_async_awaitable(
            [data_copy = std::move(data_copy)]() {
                auto container = std::make_shared<value_container>(data_copy, false);
                return container;
            });
        co_return result;
    }

References kcenon::container::async::detail::make_async_awaitable().

Here is the call graph for this function:

deserialize_streaming()

task< std::shared_ptr< value_container > > kcenon::container::async::async_container::deserialize_streaming ( std::span< const uint8_t > data, bool is_final = true )

inlinestaticnodiscard

Deserialize container progressively from chunks.

Creates a streaming deserializer that can accept data chunks progressively and build the container incrementally.

Parameters

data	Span of bytes to deserialize (can be partial)
is_final	True if this is the final chunk

Returns

task containing Result with deserialized container or error

async_container cont;
streaming_deserializer deserializer;
while (has_more_data()) {
    auto chunk = receive_chunk();
    bool is_last = !has_more_data();
    auto result = co_await deserializer.feed(chunk, is_last);
    if (is_last && result.is_ok()) {
        // Container is complete
    }
}

Definition at line 1104 of file async_container.h.

    {
        // For streaming deserialization, we accumulate data until we have a complete
        // container. In this simplified implementation, we require is_final to be true
        // to actually deserialize.
        if (!is_final) {
            co_return nullptr;
        }
 
        std::vector<uint8_t> data_copy(data.begin(), data.end());
        auto result = co_await detail::make_async_awaitable(
            [data_copy = std::move(data_copy)]() {
                auto container = std::make_shared<value_container>(data_copy, false);
                return container;
            });
        co_return result;
    }

References kcenon::container::async::detail::make_async_awaitable().

Here is the call graph for this function:

deserialize_string_async()

task< std::shared_ptr< value_container > > kcenon::container::async::async_container::deserialize_string_async ( std::string_view data )

inlinestaticnodiscard

Deserialize from string asynchronously.

Parameters

data	String containing serialized container data

Returns

task containing Result with deserialized container or error

Definition at line 903 of file async_container.h.

    {
        std::string data_copy(data);
        auto result = co_await detail::make_async_awaitable(
            [data_copy = std::move(data_copy)]() {
                auto container = std::make_shared<value_container>(data_copy, false);
                return container;
            });
        co_return result;
    }

References kcenon::container::async::detail::make_async_awaitable().

Here is the call graph for this function:

get()

template<typename T >

std::optional< T > kcenon::container::async::async_container::get ( std::string_view key ) const

inlinenodiscard

Get a value from the container.

Template Parameters

T	Expected value type

Parameters

key

Key name

Returns

Optional containing the value if found and type matches

Definition at line 329 of file async_container.h.

        {
            auto val = container_->get(key);
            if (!val) {
                return std::nullopt;
            }
            if (auto* ptr = std::get_if<T>(&val->data)) {
                return *ptr;
            }
            return std::nullopt;
        }

References container_.

get_container()

std::shared_ptr< value_container > kcenon::container::async::async_container::get_container ( ) const

inlinenodiscardnoexcept

Get the underlying container.

Returns

Shared pointer to the wrapped value_container

Examples

async_coroutine_example.cpp.

Definition at line 207 of file async_container.h.

        {
            return container_;
        }

References container_.

load_async()

task< bool > kcenon::container::async::async_container::load_async ( std::string_view path, progress_callback callback = nullptr )

inlinenodiscard

Load container from file asynchronously.

Reads the file in a worker thread and deserializes the content into the container.

Parameters

path	File path to load from
callback	Optional progress callback

Returns

task containing VoidResult indicating success or error

async_container cont;
auto result = co_await cont.load_async("data.bin");
if (result.is_ok()) {
    // Container now contains loaded data
}

Examples

async_coroutine_example.cpp.

Definition at line 915 of file async_container.h.

    {
        auto container = container_;
        std::string path_str(path);
        auto result = co_await detail::make_async_awaitable(
            [container, path_str, callback]() {
                std::ifstream file(path_str, std::ios::binary | std::ios::ate);
                if (!file) {
                    return false;
                }
 
                auto size = file.tellg();
                if (size < 0) {
                    return false;
                }
                file.seekg(0, std::ios::beg);
 
                std::vector<uint8_t> buffer(static_cast<size_t>(size));
                const size_t chunk_size = 64 * 1024;  // 64KB chunks
                size_t bytes_read = 0;
 
                while (bytes_read < static_cast<size_t>(size)) {
                    size_t to_read = std::min(chunk_size,
                        static_cast<size_t>(size) - bytes_read);
                    file.read(reinterpret_cast<char*>(buffer.data() + bytes_read),
                        static_cast<std::streamsize>(to_read));
                    if (!file) {
                        return false;
                    }
                    bytes_read += to_read;
                    if (callback) {
                        callback(bytes_read, static_cast<size_t>(size));
                    }
                }
 
                container->deserialize(buffer, false);
                return true;
            });
        co_return result;
    }

References container_, and kcenon::container::async::detail::make_async_awaitable().

Here is the call graph for this function:

operator=() [1/2]

async_container & kcenon::container::async::async_container::operator= ( async_container && other )

defaultnoexcept

Move assignment operator.

operator=() [2/2]

async_container & kcenon::container::async::async_container::operator= ( const async_container & )

delete

save_async()

task< bool > kcenon::container::async::async_container::save_async ( std::string_view path, progress_callback callback = nullptr )

inlinenodiscard

Save container to file asynchronously.

Serializes the container and writes to file in a worker thread.

Parameters

path	File path to save to
callback	Optional progress callback

Returns

task containing VoidResult indicating success or error

async_container cont;
cont.set("key", "value");
auto result = co_await cont.save_async("output.bin");
if (result.is_ok()) {
    // Data saved successfully
}

Definition at line 957 of file async_container.h.

    {
        auto container = container_;
        std::string path_str(path);
        auto result = co_await detail::make_async_awaitable(
            [container, path_str, callback]() {
                auto serialize_result = container->serialize(serialization_format::binary);
                if (!serialize_result.is_ok()) {
                    return false;
                }
                auto data = serialize_result.value();
                if (data.empty()) {
                    return false;
                }
 
                std::ofstream file(path_str, std::ios::binary);
                if (!file) {
                    return false;
                }
 
                const size_t chunk_size = 64 * 1024;  // 64KB chunks
                size_t bytes_written = 0;
                const size_t total_size = data.size();
 
                while (bytes_written < total_size) {
                    size_t to_write = std::min(chunk_size, total_size - bytes_written);
                    file.write(reinterpret_cast<const char*>(data.data() + bytes_written),
                        static_cast<std::streamsize>(to_write));
                    if (!file) {
                        return false;
                    }
                    bytes_written += to_write;
                    if (callback) {
                        callback(bytes_written, total_size);
                    }
                }
 
                return true;
            });
        co_return result;
    }

References container_, and kcenon::container::async::detail::make_async_awaitable().

Here is the call graph for this function:

serialize_async()

task< std::vector< uint8_t > > kcenon::container::async::async_container::serialize_async ( ) const

inlinenodiscard

Serialize container to byte array asynchronously.

Offloads serialization to a worker thread and returns a task that completes when serialization is done.

Returns

task containing Result with serialized bytes or error

async_container cont(my_container);
auto result = co_await cont.serialize_async();
if (result.is_ok()) {
    auto& bytes = result.value();
    // Use serialized bytes
} else {
    // Handle error
}

Definition at line 869 of file async_container.h.

    {
        auto container = container_;
        auto result = co_await detail::make_async_awaitable([container]() {
            auto serialize_result = container->serialize(serialization_format::binary);
            return serialize_result.is_ok() ? serialize_result.value() : std::vector<uint8_t>{};
        });
        co_return result;
    }

References container_, and kcenon::container::async::detail::make_async_awaitable().

Here is the call graph for this function:

serialize_chunked()

generator< std::vector< uint8_t > > kcenon::container::async::async_container::serialize_chunked ( size_t chunk_size = 64 * 1024 ) const

inlinenodiscard

Serialize container in chunks using generator.

Returns a generator that yields chunks of serialized data. Useful for streaming large containers without loading everything into memory at once.

Parameters

chunk_size

Size of each chunk in bytes (default: 64KB)

Returns

Generator yielding chunks of serialized data

async_container cont(my_container);
for (auto chunk : cont.serialize_chunked(32 * 1024)) {
    network_send(chunk);
}

Definition at line 1079 of file async_container.h.

    {
        auto serialize_result = container_->serialize(serialization_format::binary);
        if (!serialize_result.is_ok()) {
            co_return;
        }
        auto full_data = serialize_result.value();
        if (full_data.empty()) {
            co_return;
        }
 
        const size_t total_size = full_data.size();
        size_t offset = 0;
 
        while (offset < total_size) {
            size_t current_chunk_size = std::min(chunk_size, total_size - offset);
            std::vector<uint8_t> chunk(
                full_data.begin() + static_cast<std::ptrdiff_t>(offset),
                full_data.begin() + static_cast<std::ptrdiff_t>(offset + current_chunk_size));
            offset += current_chunk_size;
            co_yield chunk;
        }
    }

References container_.

serialize_string_async()

task< std::string > kcenon::container::async::async_container::serialize_string_async ( ) const

inlinenodiscard

Serialize container to string asynchronously.

Returns

task containing Result with serialized string or error

Definition at line 880 of file async_container.h.

    {
        auto container = container_;
        auto result = co_await detail::make_async_awaitable([container]() {
            auto serialize_result = container->serialize_string(serialization_format::binary);
            return serialize_result.is_ok() ? serialize_result.value() : std::string{};
        });
        co_return result;
    }

References container_, and kcenon::container::async::detail::make_async_awaitable().

Here is the call graph for this function:

set()

template<typename T >

async_container & kcenon::container::async::async_container::set ( std::string_view key, T && value )

inline

Set a value in the container.

Template Parameters

T	Value type

Parameters

key	Key name
value	Value to set

Returns

Reference to this async_container for chaining

Definition at line 316 of file async_container.h.

        {
            container_->set(key, std::forward<T>(value));
            return *this;
        }

References container_.

set_container()

void kcenon::container::async::async_container::set_container ( std::shared_ptr< value_container > container )

inlinenoexcept

Set the underlying container.

Parameters

container

New container to wrap

Definition at line 216 of file async_container.h.

        {
            container_ = std::move(container);
        }

References container_.

Member Data Documentation

container_

std::shared_ptr<value_container> kcenon::container::async::async_container::container_

private

Definition at line 471 of file async_container.h.

Referenced by contains(), get(), get_container(), load_async(), save_async(), serialize_async(), serialize_chunked(), serialize_string_async(), set(), and set_container().

---

The documentation for this class was generated from the following file:

• internal/async/async_container.h