serializable.h File Reference

ADL-based customization points that make a custom C++ type serializable through a11::data::SerializationRegistry. More...

#include <cstdint>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
#include <absl/status/status.h>
#include <absl/status/status_macros.h>
#include <absl/status/statusor.h>
#include <absl/strings/str_cat.h>
#include <nlohmann/json.hpp>
#include "a11/data/serial_tags.h"
#include "a11/data/serialization.h"
#include "a11/data/types.h"
#include "a11/json_codec.h"

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	a11::data::TypeTag< T >
	Empty tag carrying a type T so customization points are found by argument-dependent lookup even when T does not appear elsewhere in the call (e.g. More...

Namespaces
namespace	a11
namespace	a11::data
namespace	a11::data::serializable_internal

Concepts
concept	a11::data::serializable_internal::HasSerialTag
concept	a11::data::serializable_internal::HasJson
concept	a11::data::serializable_internal::HasMsgpackBytes
concept	a11::data::JsonSerializable
	Whether T provides an ADL JSON representation.
concept	a11::data::MsgpackSerializable
	Whether T can be serialized to MessagePack, either directly via A11ToMsgpackBytes / A11FromMsgpackBytes or derived from its JSON form.
concept	a11::data::Serializable
	Whether T supports at least one representation.
concept	a11::data::HasSerialTypeTag
	Whether T publishes a serialisation tag.

Functions
std::string_view	a11::data::A11SerialTag (TypeTag< ChunkMetadata >)
std::string_view	a11::data::A11SerialTag (TypeTag< Chunk >)
std::string_view	a11::data::A11SerialTag (TypeTag< NodeRef >)
std::string_view	a11::data::A11SerialTag (TypeTag< NodeFragment >)
std::string_view	a11::data::A11SerialTag (TypeTag< Port >)
std::string_view	a11::data::A11SerialTag (TypeTag< ActionMessage >)
std::string_view	a11::data::A11SerialTag (TypeTag< WireMessage >)
template<typename T >
std::string	a11::data::serializable_internal::SerialTag ()
template<typename T > requires serializable_internal::HasSerialTag<T>
std::string	a11::data::SerialTypeTag ()
template<typename T > requires JsonSerializable<T>
absl::Status	a11::data::RegisterJsonSerializable (SerializationRegistry &registry)
	Registers a JSON codec (media type application/json) for T.
template<typename T > requires MsgpackSerializable<T>
absl::Status	a11::data::RegisterMsgpackSerializable (SerializationRegistry &registry)
	Registers a MessagePack codec (media type application/x-msgpack) for T, using direct bytes when available or deriving from JSON.
template<typename T > requires Serializable<T>
absl::Status	a11::data::RegisterSerializable (SerializationRegistry &registry, bool json=true, bool msgpack=true)
	Registers every representation T supports into registry.

Detailed Description

ADL-based customization points that make a custom C++ type serializable through a11::data::SerializationRegistry.

A type opts in by defining a handful of free functions in its own namespace, found by argument-dependent lookup via the a11::data::TypeTag<T> tag:

namespace my::ns {
struct Widget { ... };
 
// Required: the language-agnostic type tag written into the chunk mimetype
// (e.g. "application/json;type=my.ns.Widget").
std::string_view A11SerialTag(a11::data::TypeTag<Widget>);
 
// JSON representation (optional; enables the application/json codec).
absl::StatusOr<nlohmann::json> A11ToJson(const Widget&);
absl::StatusOr<Widget> A11FromJson(a11::data::TypeTag<Widget>,
                                   const nlohmann::json&);
 
// MessagePack representation (optional). When omitted but JSON is present,
// MessagePack is derived from the JSON form automatically.
absl::StatusOr<std::string> A11ToMsgpackBytes(const Widget&);
absl::StatusOr<Widget> A11FromMsgpackBytes(a11::data::TypeTag<Widget>,
                                           std::string_view);
}  // namespace my::ns

Then a single call registers every representation the type supports:

RegisterSerializable<my::ns::Widget>(registry);

RegisterSerializable wraps the ADL functions into the registry's Serializer/Deserializer pairs, using the tag returned by A11SerialTag as the wire type name. The registry appends the ;type=<tag> parameter and matches it on decode.