inspect_writable/lib.rs
1// Copyright 2020 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5//! The `inspect-writable` library defines traits for simple data structures that can be
6//! written to inspect and exports a procedural macro to implement these traits.
7
8// TODO(jsankey): More documentation and examples when this is stable, and try to move it
9// somewhere into inspect contrib.
10
11// Re-export the derive-macro.
12pub use inspect_writable_derive::*;
13
14use fuchsia_inspect::Node;
15
16/// A datatype that may be written to an inspect type. This trait can be automatically derived for
17/// structs composed of inspect-compatible fields, i.e. signed integers, unsigned integers, or types
18/// implementing the `Debug` trait.
19pub trait InspectWritable: Sized {
20 /// The wrapper type returned from `create` calls.
21 type NodeType: InspectWritableNode<Self>;
22
23 /// Writes the contents of the struct into inspect fields on the supplied node. Field names
24 /// match the fields in the struct. This function uses the `create*` methods in the inspect
25 /// API and returns an `InspectWriteableNode` that may be used to update the fields in the
26 /// future.
27 fn create(&self, node: Node) -> Self::NodeType;
28
29 /// Writes the contents of the struct into inspect fields on the supplied node. Field names
30 /// match the fields in the struct. This function uses the `record*` methods in the inspect
31 /// API and should be used for fields that are never modified.
32 fn record(&self, node: &Node);
33}
34
35/// A wrapper around an Inspect node and a collection of inspect fields. These fields are created
36/// and may updated using the contents of an `InspectWritable` struct. A struct implementing
37/// `InspectWritableNode` is automatically generated when the `InspectWritable` trait is derived.
38pub trait InspectWritableNode<T: InspectWritable> {
39 /// Create a new instance, wrapping the supplied `node`. Inspect fields are created with names
40 /// matching those in the `InspectWritable` struct and initialized to the values in `data`.
41 fn new(data: &T, node: Node) -> Self;
42
43 /// Updates all inspect fields to the values in `data`.
44 fn update(&self, data: &T);
45
46 /// Returns a reference to the wrapped inspect `Node`.
47 fn inspect_node(&self) -> &Node;
48}