API Review for C/C++ Library: syslog structured backend

[Christopher Johnson]

Hello API Council,

I am reviewing https://fuchsia-review.googlesource.com/c/fuchsia/+/558253, a new C/C++ library, and a few things came up in the review I would like another set of eyes on.

For context, the CL is adding a new low-level logging library to the IDK. This library is meant to be used by system integrators as a backend for existing logging libraries to support Fuchsia structured logging. The library supports logging plaintext messages, structured key/value pairs, and late-interpolated C-style printf values (where the final string is interpolated by the reader, rather than the writer). A README is available here: https://fuchsia-review.googlesource.com/c/fuchsia/+/558253/12/sdk/lib/syslog/structured_backend/README.md. We plan to separately publish an opinionated Fuchsia logging library built on top of this library for clients who do not already have their own cross-platform logging solution.

The primary areas we would like some advice on are:

1. Overall organization of the libraries (see https://fuchsia-review.googlesource.com/c/fuchsia/+/558253/comments/c1188724_a2620f36)

The primary implementation of the library is in C++, and we provide both a C++ API (using string_view for strings) and a C API (using char*/size_t for strings). There is an opaque type called log_buffer_t that must be allocated by the caller of the library (typically on the stack), and in C++ there is a wrapper around log_buffer_t called fuchsia_syslog::LogBuffer.

What is the preferred organization of this library structure? The current implementation has only a single library at //sdk/lib/syslog/structured_backend that exposes the C and C++ header files at their appropriate locations. Is this OK, or should we have a separate cpp BUILD file and target?

2. Naming. The C API Rubric says that the "tag" for a library must be a single word without underscores ([a-z][a-z0-9]*). The library is called structured_backend, and it is logically part of the "syslog" group of libraries. Does this naming violate the rubric? What would be an acceptable name? Should the rubric be updated?

Thank you,

Christopher

[Roland McGrath]

As to the structure of a library with both C and C++ APIs, having a single library is fine when it's distributed in the SDK as source.  The only technical/policy constraints arise when we're distributing something in only binary form in the SDK.  I think otherwise it's a local choice of design and implementation detail.

I think we have other examples of all the permutations:

• a single library with both C and C++ APIs
• an implementation library in C++ with a C++ API +  a separate C wrapper API library built around the C++ API
• an implementation library in C with a C API + a separate C++ wrapper API library built around the C API

We generally encourage all implementation code to be in C++ rather than in C now.  So I think the first and second cases above are what we'd expect for new code.

What we don't allow by policy is a library with a C++ API that is distributed in binary form in the SDK.  A library can be published in the SDK in binary form if it has a C-only ABI.  So a library implemented in C++ that's not itself distributed as source in the SDK can be used internally by the implementation of a C-only API/ABI library published in binary form.  Or a C++ wrapper library can be published in the SDK In source form that relies on a C-only library published in binary form.

--
You received this message because you are subscribed to the Google Groups "api-council" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-council...@fuchsia.dev.
To view this discussion on the web visit https://groups.google.com/a/fuchsia.dev/d/msgid/api-council/CAGLaLppkOAgqp0HN61KmaWQ9MHuAsxw6ESy%2BcMD3ybJzSuiMEw%40mail.gmail.com.

[Christopher Johnson]

Thank you for your reply, Roland!

Does this mean that it is OK for "//sdk/lib/syslog/structured_backend" to publish both "<lib/syslog/structured_backend/fuchsia_syslog.h>" as well as "<lib/syslog/structured_backend/cpp/fuchsia_syslog.h>" in the SDK?

The library is being exported completely as a source set.

- Chris

[Roland McGrath]

I know of no problem with doing that.