Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Shards in rust
Implementing a new shard
To create a new shards and register it to the system, do the following.
Create a struct
The struct should contain any field necessary for the shard, especially parameters. They don't need to be pub
.
Implement the Default trait
All declared fields should be given a default value. Avoid using ..Default::default()
and initialize all fields.
Note that ParamVar::default()
is equivalent to setting nil
in the textual language. That parameter will have the None
type by default. To specify a different default value (for instance an integer), use the Paramvar::new()
constructor:
Implement the Shard trait (required)
The trait is defined in rust/src/shard.rs
. Some functions have a default implementation. At minimum the following must be implemented:
Implement registerName()
, hash()
, name()
These functions are used to identify the shard by name.
Note: registerName()
and name()
are very similar. The &str
returned by registerName()
is used on the C++ side and thus is requires to be null-terminated, which is made possible with the cstr!
macro.
Implement inputTypes()
, outputTypes()
These functions define the accepted input types and the expected output types of the shard. It can be any type including None
and Any
.
Note: a shard that doesn't use its input could be accepting and producing None
. However, it limits the usability of that shard, and we usually prefer to have the input "pass through", in which case we accept Any
type and return the same.
Implement activate()
This function is called every tick of the wire owning an instance of this shard. This is where the main logic should be implemented.
It receives the input
of the shard and should return an output (it can be Var::default()
, which is the equivalent of None
).
Implement the Shard trait (parameters)
If the shards has parameters, additional functions should be implemented.
Implement parameters()
If the shard has parameters, this function should return of description of them. Usually this is done in two steps:
- Define a static variable to hold the description.
- Return an immutable ref of that variable in the
parameters()
function.
lazy_static!
Implement setParam()
, getParam()
Since the shard has parameters, we need to implement their getters and setters. The parameter index matches the order of definition in the Parameters
struct returned by parameters()
.
Implement warmup()
, cleanup()
Some parameters are saved as ParamVar
or ShardsVar
. Those types need special care to manage the underlying memory.
Note: by convention cleanup()
uses the reverse order of warmup()
. This prevents some potential issues with dependent resources, though it might occur only in rare cases.
Implement the Shard trait (other)
Finally, if the shard has other shards as parameters, has additional type checks, or if it should expose variables; then other functions might need to be implemented.
Implement hasCompose()
, compose()
Note: to save processing, the compose()
function is only called if the hasCompose()
function returns true
. Therefore, each time compose()
needs to be implemented, so does hasCompose()
.
Implement exposedVariables()
Implement this function when a shard can receive a variable as parameter that doesn't exist (i.e. is not declared elsewhere). In this case, the shard will expose that variable for other shards to use.
The exposed
vector needs to be owned by the shard. Hence, it must be defined as a field and properly initialized in the Default
impl.
In addition, the variable should only be exposed if it doesn't exist yet. We can check whether that's the case during compose:
Implement requiredVariables()
In a similar but opposite way to exposedVariables()
, a shard might require that a variable exists.
The requiring
vector needs to be owned by the shard. Hence, it must be defined as a field and properly initialized in the Default
impl.
Note: exposing and requiring the same variable is illogical and likely a bug that needs to be fixed.
Register the shard
Once a shard is ready, it must be registered. Usually it is done in a registerShards()
function defined in a mod.rs
file:
That function itself is eventually called from, registerRustShards()
defined in rust/src/lib.rs
(either directly or through other functions).