From 2bc8a5d7c66871d200e38ec54848680e27848505 Mon Sep 17 00:00:00 2001 From: Noah Gold Date: Tue, 12 Mar 2024 23:07:56 -0700 Subject: [PATCH] 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 Commit-Queue: Noah Gold Reviewed-by: Vikram Auradkar Reviewed-by: Frederick Mayle Reviewed-by: Cody Schuffelen --- .../style_guide_platform_specific_code.md | 38 ++++++++++++++++--- 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/docs/book/src/contributing/style_guide_platform_specific_code.md b/docs/book/src/contributing/style_guide_platform_specific_code.md index 9fe444e5a2..357d2e22e9 100644 --- a/docs/book/src/contributing/style_guide_platform_specific_code.md +++ b/docs/book/src/contributing/style_guide_platform_specific_code.md @@ -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