diff --git a/examples/examplevm.c b/examples/examplevm.c index 6657a93..f934072 100644 --- a/examples/examplevm.c +++ b/examples/examplevm.c @@ -83,7 +83,7 @@ static struct evm_result evm_execute(struct evm_instance* instance, ret.output_data = output_data; ret.output_size = address_size; ret.release = &free_result_output_data; - ret.internal_memory = NULL; // We don't need another pointer. + ret.context = NULL; // We don't need another pointer. return ret; } diff --git a/include/evm.h b/include/evm.h index 932fb6c..abef3f9 100644 --- a/include/evm.h +++ b/include/evm.h @@ -106,20 +106,33 @@ struct evm_result { /// The size of the output data. size_t output_size; - /// The pointer to the result release implementation. + /// The pointer to a function releasing all resources associated with + /// the result object. /// - /// This function pointer may be set by the EVM implementation and must be - /// used by the user to release memory associated with the result object. - /// In case it is NULL the user does not have to release any resources. + /// This function pointer is optional (MAY be NULL) and MAY be set by + /// the EVM implementation. If set it MUST be used by the user to + /// release memory and other resources associated with the result object. + /// After the result resources are released the result object + /// MUST NOT be used any more. + /// + /// The suggested code pattern for releasing EVM results: + /// @code + /// struct evm_result result = ...; + /// if (result.release) + /// result.release(&result); + /// @endcode /// /// @note /// It works similarly to C++ virtual destructor. Attaching the release /// function to the result itself allows EVM composition. evm_release_result_fn release; - /// The pointer to EVM-owned memory. For EVM internal use. - /// @see output_data. - void* internal_memory; + /// The optional pointer to an internal EVM context. + /// + /// This field MAY be used by _EVM implementations_ to store additional + /// result context (e.g. memory buffers). The pointer value MUST NOT + /// be accessed nor changed by EVM users. + void* context; }; /// The query callback key.