VE_Result.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME: VE_Result.h (C++)
 *
 * COMMENTS:
 *
 *
 */

#ifndef __VE_RESULT_H__
#define __VE_RESULT_H__

#include <UT/UT_UniquePtr.h>
#include <UT/UT_WorkBuffer.h>

#include "VE_API.h"
#include "VE_VK.h"
#include <variant>

template <typename T, typename E>
class [[nodiscard]] VE_ResultBase
{
public:
    VE_ResultBase(T &&t) : myItem(std::move(t)){};
    VE_ResultBase(E &&e) : myItem(std::move(e)){};

    static VE_ResultBase<T, E> copyFrom(T t) { return VE_ResultBase(std::move(t)); }

    /// Returns true if we have a valid result. Otherwise, we have an error.
    bool ok() const { return std::holds_alternative<T>(myItem); }

    /// Moves the value out of result. Once this is called, the VE_ResultBase
    /// object is in an undefined state and MUST NOT be accessed again.
    T &&unpack()
    {
        auto t = std::get_if<T>(&myItem);
        UT_ASSERT(t);
        return std::move(*t);
    }

    /// Moves the error out of result. Once this is called, the VE_ResultBase
    /// object is in an undefined state and MUST NOT be accessed again.
    E &&error()
    {
        auto t = std::get_if<E>(&myItem);
        UT_ASSERT(t);
        return std::move(*t);
    }

    /// Copies the value out for classes that suuport copying, allowing result
    /// to still be used.
    /// I am not sure if this is an actually a useful method to have, and am
    /// worried it might provide a false sense of safety around accessing result
    /// values multiply times.
    T peek()
    {
        auto t = std::get_if<T>(&myItem);
        UT_ASSERT(t);
        return *t;
    }

protected:
    std::variant<T, E> myItem;
};

class VE_API VE_Error
{
public:
    using CodeType = uint32_t;

    enum class Code : CodeType
    {
        success,
        generic_error,
        instance_creation_failed,
        extension_unavailable,
        extension_not_enabled,
        extension_name_collision,
        layer_not_present,
        feature_unavailable,
        failed_to_enumerate_devices,
        failed_to_enumerate_device_extension_properties,
        device_creation_failed,
        vma_allocator_creation_failed,
        image_creation_failed,
        buffer_creation_failed,
        memory_map_failed,
        out_of_host_memory,
        out_of_device_memory,
        ray_tracing_support_unavailable,
        swift_shader_unavailable,
    };

    static constexpr Code code_from_vk_result(VkResult);
    static constexpr const char *message_from_code(Code);

    VE_Error() : myCode(Code::generic_error) {}
    VE_Error(Code c) : myCode(c) {}
    VE_Error(VkResult r) : myCode(code_from_vk_result(r)) {}
    VE_Error(Code c, VkResult r) : myCode(c), myVkResult(r) {}

    template <typename... Args>
    VE_Error(Code c, const char *fmt, const Args &...args) : myCode(c)
    {
        if (!myMsg)
            myMsg = UTmakeUnique<UT_WorkBuffer>();
        myMsg->format(fmt, args...);
    }

    template <typename... Args>
    VE_Error(const char *fmt, const Args &...args) : myCode(Code::generic_error)
    {
        if (!myMsg)
            myMsg = UTmakeUnique<UT_WorkBuffer>();
        myMsg->format(fmt, args...);
    }

    template <typename... Args>
    void appendFormat(const char *fmt, const Args &...args)
    {
        if (!myMsg)
            myMsg = UTmakeUnique<UT_WorkBuffer>();
        myMsg->appendFormat(fmt, args...);
    }

    const char *message() const
    {
        if (!myMsg)
        {
            return message_from_code(myCode);
        }
        return myMsg->buffer();
    }

    void printMsg() const
    {
        fprintf(stderr, "VE_Error: %s\n", message());
        if (myVkResult != VK_SUCCESS)
        {
            fprintf(stderr, "VkResult code: %d\n", myVkResult);
        }
    }

    Code code() const { return myCode; }

private:
    Code myCode;
    VkResult myVkResult = VK_SUCCESS;
    UT_UniquePtr<UT_WorkBuffer> myMsg;
};

/// A class to contain either a value or an error.
/// It is meant to provide a value-semantics based approached to error handling,
/// allowing functions to return either a value or an error in the same type.
///
/// It currently works with any value type provided it is moveable. Future work
/// could be done to support classes that are copy-able but not moveable, though
/// I think such types are rarer in practice.
/// 
/// Example usage:
///
/// VE_Result<SomeType> 
/// fooBar()
/// {
///     Usage pattern is generally this:
///
///     auto result = functionThatCanError();
///     if (!result.ok())
///         // Error can be handled or bubbled up to caller.
///         return result.error();
///
///     // Note that this moves the value out of result and so
///     // result must not be accessed again beyond this point.
///     auto payload = result.unpack();
///
///     SomeType st(payload);
///
///     // Type is automatically converted to Result<Type>
///     return st;
/// }
///
template <typename T>
class [[nodiscard]] VE_Result : public VE_ResultBase<T, VE_Error>
{
public:
    using Base = VE_ResultBase<T, VE_Error>;

    VE_Result() : Base(VE_Error(VE_Error::Code::generic_error)) {}

    VE_Result(T &&t) : Base(std::move(t)) {}
    VE_Result(VE_Error &&e) : Base(std::move(e)){}
    VE_Result(VE_Error::Code c) : Base(VE_Error(c)){}

    static VE_Result<T> copyFrom(T t) { return VE_Result(std::move(t)); }

    T value()
    {
        return Base::peek();
    }
};

using VE_VoidResult = VE_Result<std::monostate>;

static inline VE_VoidResult
VEvoidSuccess()
{
    return VE_VoidResult(std::monostate());
}

constexpr inline VE_Error::Code
VE_Error::code_from_vk_result(VkResult r)
{
    using c = VE_Error::Code;

    switch (r)
    {
        case VK_SUCCESS:
            return c::success;
        case VK_ERROR_OUT_OF_HOST_MEMORY:
            return c::out_of_host_memory;
        case VK_ERROR_OUT_OF_DEVICE_MEMORY:
            return c::out_of_device_memory;
        case VK_ERROR_MEMORY_MAP_FAILED:
            return c::memory_map_failed;
        case VK_ERROR_LAYER_NOT_PRESENT:
            return c::layer_not_present;
        default:
            return c::generic_error;
    }
}

constexpr const char *VE_Error::message_from_code(VE_Error::Code c)
{
    switch (c)
    {
        case VE_Error::Code::success: return "success";
        case VE_Error::Code::instance_creation_failed: return "failed to create vulkan instance";
        case VE_Error::Code::extension_unavailable: return "extension unavailable";
        case VE_Error::Code::extension_name_collision: return "extension name collision";
        case VE_Error::Code::layer_not_present: return "instance layer is not present";
        case VE_Error::Code::feature_unavailable: return "feature is unavailable";
        case VE_Error::Code::failed_to_enumerate_devices: return "failed to enumerate devices";
        case VE_Error::Code::failed_to_enumerate_device_extension_properties: return "failed to enumerate extension properties";
        case VE_Error::Code::device_creation_failed: return "device creation failed";
        case VE_Error::Code::vma_allocator_creation_failed: return "vma allocator creation failed";
        case VE_Error::Code::image_creation_failed: return "image creation failed";
        case VE_Error::Code::buffer_creation_failed: return "buffer creation failed";
        case VE_Error::Code::memory_map_failed: return "memory mapping failed";
        case VE_Error::Code::out_of_host_memory: return "out of host memory";
        case VE_Error::Code::out_of_device_memory: return "out of video memory";
        case VE_Error::Code::extension_not_enabled: return "extension is not enabled";
        case VE_Error::Code::generic_error: return "error";
        case VE_Error::Code::ray_tracing_support_unavailable: return "ray tracing support unavailable";
        case VE_Error::Code::swift_shader_unavailable: return "swift shader unavailable";
    }

    return "error";
}

#endif