Pigweed Live Notes: 2023-11-06

[chadn...@google.com]

2023-11-06

Landed recently highlights (full changelog)

• C++14 is out and C++17 is in - Pigweed now requires C++17 or newer
• pw_format is a new module dedicated to Rust format string parsing.
• Build system updates
• The upstream Pigweed GN build is now more isolated so that downstream projects have less conflicts when importing Pigweed into their existing GN build.
• Build configuration is moving away from Bazel macros like pw_cc_library and towards the toolchain configuration so that downstream projects can have full control over how Pigweed libraries are built.

Active SEEDs

• 0103: pw_protobuf Object Model
• 0106: Project Template
• 0110: Memory Allocation Interfaces
• 0113: Modular Bazel C/C++ Toolchain API
• 0114: Channels
• 0115: Sensors
• 0116: Sockets

Agenda & Notes

Updated module documentation guidelines -

Kayce Basques

• Background: SEED-0102 was our first attempt at helping module owners create high-quality docs. Some things worked well, others didn't clearly lead to better docs.
• Module Docs Guidelines are the new guidelines. Basically all the guidelines are based off stuff we learned from SEED-0102.
• We're focused on "simple" modules similar to pw_string: "user"/HAL-facing, doesn't use facades, small-ish API surface, supports 1 language only
• Talk to me if you need help with the docs for a "non-simple" module
• Feedback requests
• Do the new module docs guidelines make sense?
• Are the new docs that we're creating based off the new guidelines actually helpful/intuitive/etc. for you? pw_string is our first "golden" docs set.
• Discussion
• Aaron Green
  another criteria for simple/complex could be how detailed the API usage is. E.g. sometimes you have only 3 methods but it takes a few pages to explain how to use it in all these different situations.
• Armando Montanez
  what's the process for updating the guidelines? E.g. proposing that something should be added or removed.
• Kayce Basques
  Discuss here in Pigweed Live?
• API docs:
• Split opinions over alphabetical vs conceptual organization
• Maybe we should default to including a function in Doxygen instead of defaulting to excluding it (unless it has a /// comment) – otherwise you risk having incomplete API docs, forcing the reader to look at the code as the source of truth
• Questions about how to include a snippet from a test into Doxygen
• Lots of interest in low-level mechanics of using Doxygen to accomplish certain tasks
• Tom: Please be careful to not let Doxygen markup get in the way too much of being able to look at the source code and understand the big picture.

Channels - part of Pigweed Comms 2.0 effort

• Channels are slated to be Pigweed's "file descriptor" equivalent that support zero-copy and backpressure semantics.
• SEED 0114: Channels
• SEED 0116: Sockets - builds on the above
• Channels let you read, write, and seek buffers - not all channels support all of these operations, so there are mechanisms for determining what a channel supports
• Feedback: We should learn from the digital IO API class structure design process, which took effort and iterations to get to a sensible place – this case is similar, where there are several capabilities that concrete classes may or may not support in various combinations. These are more like orthogonal dimensions rather than a strict class hierarchy
• E.g., could there be a channel that supports both byte streaming and datagrams? In that case, the proposed class hierarchy breaks down
• Rust traits seem like an ideal way to represent this – but how do you do that in C++? One approach is templates that constrain convertability between types
• Should the API be bidirectional? Or should the readable bits be separated from the writable bits?
• There are a lot of cases where an instance is only going be consumed as a reader or as a writer
• It’s really nice to enforce this in the type system, e.g., something that can only be read from can be directed into something that can only be written to, enforced up front
• It’s unsatisfying/confusing to have an object with a bunch of methods that exist but can’t actually be used
• Could handle this by having a “slimming down” class that takes a bidirectional type and represents it as just a reader or writer
• Example: a UART drain queue, which would be only read from when draining, and only written to when putting things on the queue. Should these be literally the same object? The API consumers only need a reader and a writer respectively, and the other half shouldn’t be exposed
• Runtime enforcement + compile time flags?
• This is conceptually similar to Unix file descriptors – they have input/output “APIs”, but it’s contextual as to whether a particular fd can be read from or written to

Sent from document [PUBLIC] Pigweed Live Notes