ark-api-ffi 0.16.0

Ark low-level Wasm FFI API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

//! Behavior module entrypoints

/// `ark_behavior_register` - Register a behavior module
///
/// Register a behavior module by returning a serialized JSON vector of bytes of local registration info.
pub type BehaviorRegisterFn = fn();

/// `ark_behavior_persist` - Persists the whole dynamic state of a behavior module
///
/// Allows saving the whole state of a behavior module, notably before trying to re-spawn the
/// behavior module after it failed.
///
/// The persistence format choice is left to the behavior module, and it has to be same used in the
/// corresponding `ark_behavior_restore` function.
///
/// If this function panics, the attempt to re-spawm the behavior module is aborted, and the
/// initial error that caused the behavior module panic is reported to the user.
///
/// For persisting singular behavior instances, prefer to use the `ark_behavior_instance_persist`
/// function instead.
///
/// This uses Ark's return slice mechanism to store the persisted vector of raw bytes.
pub type BehaviorPersistFn = fn();

/// `ark_behavior_restore` - Restores the whole dynamic state of a behavior module
///
/// This will be passed the state created by `ark_behavior_persist`, so as to restore the whole
/// module's dynamic state. The same serialization format chosen in `ark_behavior_persist` must be
/// used by this function.
///
/// If this function panics, the attempt to re-spawm the behavior module is aborted, and the
/// initial error that caused the behavior module panic is reported to the user.
pub type BehaviorRestoreFn = fn(state_ptr: u32, state_size: u32);

/// `ark_behavior_instance_create` - Create a behavior instance
///
/// Create a behavior instance of the specific type with the provided serialized parameters.
pub type BehaviorInstanceCreateFn = fn(local_type_id: u32, params_ptr: u32, params_len: u32) -> u64;

/// `ark_behavior_instance_destroy` - Destroy a behavior instance
///
/// This frees the memory of the instance and the instance can no longer be accessed.
pub type BehaviorInstanceDestroyFn = fn(instance_id: u64);

/// `ark_behavior_instance_clone` - Clone a behavior instance to create a new identical instance
pub type BehaviorInstanceCloneFn = fn(instance_id: u64) -> u64;

/// `ark_behavior_instance_persist` - Persist a behavior instance by serializing it to a blob
///
/// Return the size of the serialized representation. The memory buffer itself is returned
/// through the Ark return slice mechanism `ark::core::return_slice`.
pub type BehaviorInstancePersistFn = fn(instance_id: u64);

/// `ark_behavior_instance_restore` - Restore a behavior instance by deserializing it from a persistent representation
///
/// On success returns a behavior instance id.
pub type BehaviorInstanceRestoreFn = fn(local_type_id: u32, blob_ptr: u32, blob_size: u32) -> u64;

/// `ark_behavior_instance_handle_message` - Have the specified instance process the provided message
///
/// During the execution of this entry point, the behavior instance has access to the Behavior API.
/// Through this API a behavior instance can get aspect data and write outgoing messages back to the owning controller module.
pub type BehaviorInstanceHandleMessageFn =
    fn(instance_id: u64, actor_id: u32, message_blob_ptr: u32, message_blob_size: u32);

/// `ark_behavior_instances_handle_messages` - Process the provided messages
///
/// During the execution of this entry point, the behavior instance has access to the Behavior API.
/// Through this API a behavior instance can get aspect data and write outgoing messages back to the owning controller module.
pub type BehaviorInstancesHandleMessagesFn = fn(encoded_slice_ptr: u32, encoded_slice_len: u32);

pub const BEHAVIOR_REGISTER: &str = "ark_behavior_register";
pub const BEHAVIOR_PERSIST: &str = "ark_behavior_persist";
pub const BEHAVIOR_RESTORE: &str = "ark_behavior_restore";
pub const BEHAVIOR_INSTANCE_CREATE: &str = "ark_behavior_instance_create";
pub const BEHAVIOR_INSTANCE_DESTROY: &str = "ark_behavior_instance_destroy";
pub const BEHAVIOR_INSTANCE_CLONE: &str = "ark_behavior_instance_clone";
pub const BEHAVIOR_INSTANCE_PERSIST: &str = "ark_behavior_instance_persist";
pub const BEHAVIOR_INSTANCE_RESTORE: &str = "ark_behavior_instance_restore";
pub const BEHAVIOR_INSTANCE_HANDLE_MESSAGE: &str = "ark_behavior_instance_handle_message";
pub const BEHAVIOR_INSTANCES_HANDLE_MESSAGES: &str = "ark_behavior_instances_handle_messages";