asterinas/ostd/libs/ostd-pod/macros/README.md

ostd-pod-macros

Procedural macros for the ostd-pod crate.

This crate provides procedural macros to simplify working with Plain Old Data (POD) types. It exports two main macros:

• #[derive(Pod)]: An attribute macro that expands into the underlying zerocopy traits
• #[pod_union]: An attribute macro that makes unions safe to use as POD types

The derive Macro

The #[derive(Pod)] macro is a convenience wrapper that automatically derives the required zerocopy traits for POD types.

Unlike typical derive procedural macros, derive in this crate is actually an attribute macro that works by shadowing ::core::prelude::v1::derive.

The pod_union Macro

The #[pod_union] attribute macro enables safe usage of unions as POD types. It automatically:

• Derives the necessary zerocopy traits
• Generates safe initializer and accessor methods for each union field
• Enforces #[repr(C)] layout
• Ensures all fields are POD types

Generated Initializer and Accessor Methods

For each field foo in the union, the macro generates:

• fn new_foo(value: FieldType) -> Self: Constructs an instance from the field
• fn foo(&self) -> &FieldType: Returns a reference to the field
• fn foo_mut(&mut self) -> &mut FieldType: Returns a mutable reference to the field

These methods use zerocopy's safe byte conversion methods, avoiding unsafe code.

For detailed usage examples, see the crate ostd-pod documentation.

License

This project is licensed under MPL-2.0.