actor-framework icon indicating copy to clipboard operation
actor-framework copied to clipboard

Restructure the inspector API

Open Neverlord opened this issue 3 months ago • 1 comments

We currently have various inspector in the CAF main namespace:

  • json_reader
  • json_writer
  • stringification_inspector
  • ...

To at least get the implementations details out of the public headers, we moved to a PIMPL-based approach. However, this is a one-off in CAF. We generally move towards interfaces in the public API and the factory pattern to avoid having to expose implementation details at all. Implementations should move into the internal or detail namespace (or an anonymous namespace as implementation detail of the factory).

For CAF 2.0, we should get our inspector consistent with the overall design:

  • [ ] add a new namespace for our inspectors
  • [ ] add the interfaces for out inspectors to that namespace
  • [ ] provide factory functions to get instances of the inspectors
  • [ ] re-implement and deprecate the current set of classes
  • [x] remove the fast_pimpl class again

Neverlord avatar Nov 29 '25 18:11 Neverlord

We could also consider leaving the pimpl-design as-is with a few tweaks:

  • get rid of the inheritance hierarchy for the user-facing types like json_reader
  • offer an as_serializer / as_deserializer getter on the facade types instead
  • push the current completely private implementations to the internal namespace

That way, we still get a clean separation of public and private API, allowing us to make tweaks to the implementations without breaking the ABI. Users can still write their custom serializers / deserializers if they really want to since those two interfaces remain public. However, users won't be able to inherit from the json_reader for example. I think that's a reasonably tradeoff. Pushing more classes into the internal namespace gives us more flexibility and reduces the overall API surface.

Neverlord avatar Dec 12 '25 06:12 Neverlord