book: style guide: add dispatch enum pattern.

auradkar@, fmayle@, schuffelen@, and nkgold@ discussed
the guidance for cross platform enums and have decided
to recommend a new pattern for dispatch style enums.

BUG=NONE
TEST=builds

Change-Id: I07ce234753a5c39873ae214d6407181cbd46fcf0
Reviewed-on: https://chromium-review.googlesource.com/c/crosvm/crosvm/+/5369097
Reviewed-by: Daniel Verkamp <dverkamp@chromium.org>
Commit-Queue: Noah Gold <nkgold@google.com>
Reviewed-by: Vikram Auradkar <auradkar@google.com>
Reviewed-by: Frederick Mayle <fmayle@google.com>
Reviewed-by: Cody Schuffelen <schuffelen@google.com>
This commit is contained in:
Noah Gold 2024-03-12 23:07:56 -07:00 committed by crosvm LUCI
parent ba1dad6a20
commit 2bc8a5d7c6

View file

@ -261,6 +261,38 @@ fn handle_my_enum(e: MyEnum) {
}
```
### Exception: dispatch enums (trait-object like enums) should NOT be split
Dispatch enums (enums which are pretending to be trait objects) should NOT be split as shown above.
This is because these enums just forward method calls verbatim and don't have any meaningful cross
platform code. As such, there is no benefit to splitting the enum. Here is an acceptable example:
```rust
enum MyDispatcher {
#[cfg(windows)]
WinType(ImplForWindows),
#[cfg(unix)]
UnixType(ImplForUnix),
}
impl MyDispatcher {
fn foo(&self) {
match self {
#[cfg(windows)]
MyDispatcher::WinType(t) => t.foo(),
#[cfg(unix)]
MyDispatcher::UnixType(t) => t.foo(),
}
}
}
```
## Errors
Inlining all platform specific error values is ok. This is an exception to the [enum](#enum) to keep
error handling simple. Organize platform independent errors first and then platform specific errors
ordered by the target os name i.e. "linux" first and "windows" later.
## Code blocks and functions
If a code block or a function has little platform independent code and the bulk of the code is
@ -385,12 +417,6 @@ fn parse_args(arg: &str) -> Result<()>{
}
```
## Errors
Inlining all platform specific error values is ok. This is an exception to the [enum](#enum) to keep
error handling simple. Organize platform independent errors first and then platform specific errors
ordered by the target os name i.e. "linux" first and "windows" later.
## Platform specific symbols
If a platform exports symbols that are specific to the platform only and are not exported by all