Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ cpp_library_setup(
DESCRIPTION "Checked CEL programs, owned values, and reusable execution stacks"
NAMESPACE cel
REQUIRES_CPP_VERSION 20
HEADERS runtime.hpp runtime/layout.hpp runtime/value_type.hpp runtime/value.hpp runtime/raw_stack.hpp runtime/dyn_segment.hpp runtime/callable.hpp runtime/detail/retirement.hpp runtime/detail/frame.hpp runtime/detail/raw_segment.hpp
HEADERS runtime.hpp runtime/layout.hpp runtime/value_type.hpp runtime/value.hpp runtime/record_adapter.hpp runtime/raw_stack.hpp runtime/dyn_segment.hpp runtime/callable.hpp runtime/detail/retirement.hpp runtime/detail/frame.hpp runtime/detail/raw_segment.hpp
SOURCES storage.cpp value_type.cpp value.cpp raw_stack.cpp raw_segment.cpp dyn_segment.cpp callable.cpp
TESTS storage_test.cpp value_test.cpp resource_test.cpp raw_execution_test.cpp segment_test.cpp composite_execution_test.cpp callable_test.cpp executable_retirement_test.cpp native_contract_test.cpp nontrivial_leaf_fail.cpp typed_operand_fail.cpp overloaded_operand_fail.cpp generic_conversion_fail.cpp nondeduced_generic_fail.cpp raw_interface_fail.cpp alignment_interface_fail.cpp program_metadata_fail.cpp
EXAMPLES getting_started.cpp
Expand Down
36 changes: 36 additions & 0 deletions docs/libraries.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,42 @@ stored bytes, not resources reached through pointers inside those bytes.
Use the provided `std::vector<T>` and `std::tuple<T...>` adapters for owning
arrays and tuples instead of wrapping nontrivial containers as opaque leaves.

For a nontrivial nominal record, specialize `cel::record_adapter<T>` with a
record descriptor and field-wise encode/decode callbacks:

```cpp
struct point {
double x;
double y;
};

template <>
struct cel::record_adapter<point> {
static cel::value_type type() {
static const auto descriptor = cel::value_type::record(
"sample.point",
std::array{cel::record_field{"x", cel::value_type::leaf<double>()},
cel::record_field{"y", cel::value_type::leaf<double>()}});
return descriptor;
}
static cel::value to_value(const point& source) {
return cel::value::record(type(),
std::array{cel::value::from(source.x),
cel::value::from(source.y)});
}
static point from_value(const cel::value& source) {
if (!source.type().same_shape(type()))
throw std::invalid_argument("wrong point type");
return {.x = source.field("x").as<double>(),
.y = source.field("y").as<double>()};
}
};
```

The runtime requires `type()` to be a nominal record. `value::from<T>()`
verifies that `to_value()` returns exactly that schema. `value::as<T>()` checks
complete nominal identity and schema before `from_value()`.

## Choose the result boundary

Use `prepare<R, Args...>()` when the application knows the signature.
Expand Down
1 change: 1 addition & 0 deletions include/cel/runtime.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
#include <cel/runtime/dyn_segment.hpp>
#include <cel/runtime/layout.hpp>
#include <cel/runtime/raw_stack.hpp>
#include <cel/runtime/record_adapter.hpp>
#include <cel/runtime/value.hpp>
#include <cel/runtime/value_type.hpp>

Expand Down
10 changes: 5 additions & 5 deletions include/cel/runtime/detail/frame.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,9 @@ struct borrowed_value {
/// Example: `auto n = input.as<double>();`.
template <class T>
T as() const {
const auto expected = detail::concrete_adapter<T>::type();
const auto expected = detail::boundary_adapter<T>::type();
require_type(expected);
return detail::concrete_adapter<T>::read(type, data);
return detail::boundary_adapter<T>::read(type, data);
}
};

Expand Down Expand Up @@ -111,7 +111,7 @@ class frame {
/// Complexity: native read work, result storage, and adapter auxiliary space.
template <class T>
T read_operand(std::size_t from_top, const value_type& expected) const {
return detail::concrete_adapter<T>::read(
return detail::boundary_adapter<T>::read(
expected, _stack->borrow_trusted(_checkpoint, from_top, expected));
}
/// Returns independent concrete operands in source order without consuming them.
Expand Down Expand Up @@ -155,7 +155,7 @@ class frame {
require_active();
_stack->push_written(
type, &source, [](const void* input, const value_type& shape, std::byte* destination) {
detail::concrete_adapter<T>::write(*static_cast<const T*>(input), shape,
detail::boundary_adapter<T>::write(*static_cast<const T*>(input), shape,
destination);
});
}
Expand Down Expand Up @@ -268,7 +268,7 @@ class frame {
/// Example: `scope.push(2.0);`.
template <class T>
void push(const T& source) {
push_result(detail::concrete_adapter<T>::type(), source);
push_result(detail::boundary_adapter<T>::type(), source);
}
/// Removes and returns an independent concrete copy of the top suffix operand.
///
Expand Down
4 changes: 2 additions & 2 deletions include/cel/runtime/detail/raw_segment.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -72,14 +72,14 @@ class raw_segment {
if constexpr (std::is_void_v<R>)
return std::array<value_type, 0>{};
else
return std::array{detail::concrete_adapter<R>::type()};
return std::array{detail::boundary_adapter<R>::type()};
}
/// Constructs signature metadata and an owned callback from its source.
///
/// Complexity: operand/result descriptor construction and callback construction costs.
template <class G>
requires std::constructible_from<F, G&&> explicit operation(G&& input) :
inputs{detail::concrete_adapter<Args>::type()...}, outputs(result_types()),
inputs{detail::boundary_adapter<Args>::type()...}, outputs(result_types()),
callback(std::forward<G>(input)) {}
/// Consumes source-ordered operands, invokes the callback, and publishes its result.
///
Expand Down
18 changes: 9 additions & 9 deletions include/cel/runtime/dyn_segment.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -74,9 +74,9 @@ struct stack_requirements {

namespace detail {
struct frozen_program;
/// Selects native leaf boundaries rather than unspecified standard composite layouts.
/// Selects borrowed native leaves rather than canonical record or composite layouts.
template <class T>
inline constexpr bool native_leaf = true;
inline constexpr bool native_leaf = !nominal_record_adapter<T>;
/// Selects the trusted vector adapter.
template <class T, class A>
inline constexpr bool native_leaf<std::vector<T, A>> = false;
Expand Down Expand Up @@ -539,7 +539,7 @@ class dyn_segment {
void just(value literal);
/// Emits an arbitrary-arity const callback with exact declared operands and result.
///
/// R is a trusted concrete adapter type or void; void consumes without producing a value.
/// R is a trusted native adapter type or void; void consumes without producing a value.
/// Parameter/result identities are exact after cv/reference removal. Reference results are
/// copied into an independently owned result; implicit result conversions are not admitted.
/// Use with_signature for ambiguous or uninspectable callback members. Generic members
Expand All @@ -563,12 +563,12 @@ class dyn_segment {
requires(detail::exact_callback<F, R, Args...>()) void op(F&& callback) {
static_assert((std::same_as<Args, std::remove_cvref_t<Args>> && ...));
const std::array<value_type, sizeof...(Args)> inputs{
detail::concrete_adapter<Args>::type()...};
detail::boundary_adapter<Args>::type()...};
const auto outputs = [] {
if constexpr (std::is_void_v<R>)
return std::array<value_type, 0>{};
else
return std::array{detail::concrete_adapter<R>::type()};
return std::array{detail::boundary_adapter<R>::type()};
}();
const auto effect = check_operation(inputs, outputs);
_body.template push_op<R, Args...>(
Expand Down Expand Up @@ -963,12 +963,12 @@ class prepared_segment {
if constexpr (detail::native_leaf<R>) {
alignas(R) std::array<std::byte, sizeof(R)> bytes{};
_binding.call_into(stack, views, bytes.data());
return detail::concrete_adapter<R>::read(_binding.result_type(), bytes.data());
return detail::boundary_adapter<R>::read(_binding.result_type(), bytes.data());
} else {
detail::result_storage result(_binding);
_binding.call_into(stack, views, result.data());
result.initialized();
return detail::concrete_adapter<R>::read(_binding.result_type(), result.data());
return detail::boundary_adapter<R>::read(_binding.result_type(), result.data());
}
}
};
Expand All @@ -977,8 +977,8 @@ class prepared_segment {
template <class R, class... Args>
prepared_segment<R, Args...> compiled_segment::prepare() const {
static_assert(!std::is_void_v<R>, "use tuple<> for the source-unit result");
const std::array<value_type, sizeof...(Args)> types{detail::concrete_adapter<Args>::type()...};
return prepared_segment<R, Args...>(prepare_raw(types, detail::concrete_adapter<R>::type()));
const std::array<value_type, sizeof...(Args)> types{detail::boundary_adapter<Args>::type()...};
return prepared_segment<R, Args...>(prepare_raw(types, detail::boundary_adapter<R>::type()));
}

/// @}
Expand Down
8 changes: 4 additions & 4 deletions include/cel/runtime/raw_stack.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -97,8 +97,8 @@ class raw_stack {
T read_value(std::size_t floor) {
if (depth() <= floor) throw std::out_of_range("operand underflow");
phase_guard phase(*this);
const auto type = detail::concrete_adapter<T>::type();
return detail::concrete_adapter<T>::read(type, borrow(floor, 0, type));
const auto type = detail::boundary_adapter<T>::type();
return detail::boundary_adapter<T>::read(type, borrow(floor, 0, type));
}
/// Reserves an aligned uninitialized operand extent and returns its byte offset.
///
Expand Down Expand Up @@ -288,9 +288,9 @@ class raw_stack {
template <class T>
void push(const T& source) {
require_access(nullptr);
push_written(detail::concrete_adapter<T>::type(), &source,
push_written(detail::boundary_adapter<T>::type(), &source,
[](const void* input, const value_type& type, std::byte* destination) {
detail::concrete_adapter<T>::write(*static_cast<const T*>(input), type,
detail::boundary_adapter<T>::write(*static_cast<const T*>(input), type,
destination);
});
}
Expand Down
42 changes: 42 additions & 0 deletions include/cel/runtime/record_adapter.hpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
// SPDX-License-Identifier: BSL-1.0
#ifndef CEL_RUNTIME_RECORD_ADAPTER_HPP
#define CEL_RUNTIME_RECORD_ADAPTER_HPP

#include <cel/runtime/value_type.hpp>

namespace cel {
class value;

/// Adapts one client nominal record type to and from canonical CEL record values.
///
/// Specialize this template for one client type T to expose it as a nominal record.
/// type() must return a nominal record descriptor. to_value() must return a value with
/// exactly that descriptor. from_value() should validate complete descriptor identity
/// before decoding and throw std::invalid_argument when mismatched.
///
/// Example:
/// @code
/// struct point {
/// double x;
/// double y;
/// };
///
/// template <>
/// struct cel::record_adapter<point> {
/// static cel::value_type type() {
/// static const auto descriptor = cel::value_type::record(
/// "sample.point",
/// std::array{cel::record_field{"x", cel::value_type::leaf<double>()},
/// cel::record_field{"y", cel::value_type::leaf<double>()}});
/// return descriptor;
/// }
/// static cel::value to_value(const point& source);
/// static point from_value(const cel::value& source);
/// };
/// @endcode
template <class T>
struct record_adapter {};

} // namespace cel

#endif
Loading
Loading