Crate mentat_ffi [−] [src]

This module exposes an Foreign Function Interface (FFI) that allows Mentat to be called from other languages.

Functions that are available to other languages in this module are defined as extern "C" functions which allow them to be layed out correctly for the platform's C ABI. They all have a #[no_mangle] decorator to ensure Rust's name mangling is turned off, so that it is easier to link to.

Mentat's FFI contains unsafe code. As it is an interface between foreign code and native Rust code, Rust cannot guarantee that the types and data that have been passed to it from another language are present and in the format it is expecting. This interface is designed to ensure that nothing unsafe passes through this module and enters Mentat proper

Structs defined with #[repr(C)] are guaranteed to have a layout that is compatible with the platform's representation in C.

This API passes pointers in two ways, depending on the lifetime of the value and what value owns it. Pointers to values that are guaranteed to live beyond the lifetime of the function, are passed over the FFI as a raw pointer.

value as *const Binding

Pointers to values that cannot be guaranteed to live beyond the lifetime of the function are first Boxed so that they live on the heap, and the raw pointer passed this way.

Box::into_raw(Box::new(value))

The memory for a value that is moved onto the heap before being passed over the FFI is no longer managed by Rust, but Rust still owns the value. Therefore the pointer must be returned to Rust in order to be released. To this effect a number of destructor functions are provided for each Rust value type that is passed, as is a catch all destructor to release memory for #[repr(C)] values. The destructors reclaim the memory via Box and then drop the reference, causing the memory to be released.

A macro has been provided to make defining destructors easier.

define_destructor!(query_builder_destroy, QueryBuilder);

Passing a pointer to memory that has already been released will cause Mentat to crash, so callers have to be careful to ensure they manage their pointers properly. Failure to call a destructor for a value on the heap will cause a memory leak.

Generally, the functions exposed in this module have a direct mapping to existing Mentat APIs, in order to keep application logic to a minumum and provide the greatest flexibility for callers using the interface. However, in some cases a single convenience function has been provided in order to make the interface easier to use and reduce the number of calls that have to be made over the FFI to perform a task. An example of this is store_register_observer, which takes a single native callback function that is then wrapped inside a Rust closure and added to a TxObserver struct. This is then used to register the observer with the store.

Functions that may fail take an out parameter of type *mut ExternError. In the event the function fails, information about the error that occured will be stored inside it (and, typically, a null pointer will be returned). Convenience functions for unpacking a Result<T, E> as a *mut T while writing any error to the ExternError are provided as translate_result, translate_opt_result (for Result<Option<T>>) and translate_void_result (for Result<(), T>). Callers are responsible for freeing the message field of ExternError.

Re-exports

pub use utils::strings::c_char_to_string;

pub use utils::strings::kw_from_string;

pub use utils::strings::string_to_c_char;

pub use utils::log;

Modules

android
utils

Macros

assert_not_null

Helper macro for asserting one or more pointers are not null at the same time.

Structs

EntityBuilder
InProgress	Represents an in-progress, not yet committed, set of changes to the store. Call `commit` to commit your changes, or `rollback` to discard them. A transaction is held open until you do so. Your changes will be implicitly dropped along with this struct.
InProgressBuilder
InProgressTransactResult
KnownEntid	An entid that's either already in the store, or newly allocated to a tempid. TODO: we'd like to link this in some way to the lifetime of a particular PartitionMap.
QueryBuilder
QueryInputs	Define the inputs to a query. This is in two parts: a set of values known now, and a set of types known now. The separate map of types is to allow queries to be algebrized without full knowledge of the bindings that will be used at execution time. When built correctly, `types` is guaranteed to contain the types of `values` -- use `QueryInputs::new` or `QueryInputs::with_values` to construct an instance.
QueryOutput
RelResult	The result you get from a 'rel' query, like:
Store	A convenience wrapper around a single SQLite connection and a Conn. This is suitable for applications that don't require complex connection management.
TransactionChange	A C representation of the change provided by the transaction observers from a single transact. Holds a transaction identifier, the changes as a set of affected attributes and the length of the list of changes.
TxChangeList	A C representation of the list of changes provided by the transaction observers. Provides the list of changes as the length of the list.
TxObserver
TxReport	A transaction report summarizes an applied transaction.
Uuid	A Universally Unique Identifier (UUID).
Variable

Enums

Binding	The values bound in a query specification can be:
CacheDirection
FindSpec	A definition of the first part of a find query: the `[:find ?foo ?bar…]` bit.
QueryResults
TypedValue	Represents a value that can be stored in a Mentat store.
ValueType	The attribute of each Mentat assertion has a :db/valueType constraining the value to a particular set. Mentat recognizes the following :db/valueType values.

Traits

BuildTerms
HasSchema
IntoThing
Queryable
Syncable

Functions

changelist_entry_at ^⚠	Returns the value at the provided `index` as a Entid .
destroy ^⚠
entity_builder_add_boolean ^⚠	Uses `builder` to assert `value` for `kw` on entity `entid`.
entity_builder_add_double ^⚠	Uses `builder` to assert `value` for `kw` on entity `entid`.
entity_builder_add_keyword ^⚠	Uses `builder` to assert `value` for `kw` on entity `entid`.
entity_builder_add_long ^⚠	Uses `builder` to assert `value` for `kw` on entity `entid`.
entity_builder_add_ref ^⚠	Uses `builder` to assert `value` for `kw` on entity `entid`.
entity_builder_add_string ^⚠	Uses `builder` to assert `value` for `kw` on entity `entid`.
entity_builder_add_timestamp ^⚠	Uses `builder` to assert `value` for `kw` on entity `entid`.
entity_builder_add_uuid ^⚠	Uses `builder` to assert `value` for `kw` on entity `entid`.
entity_builder_commit ^⚠	Transacts and commits all the assertions and retractions that have been performed using this builder.
entity_builder_destroy ^⚠
entity_builder_retract_boolean ^⚠	Uses `builder` to retract `value` for `kw` on entity `entid`.
entity_builder_retract_double ^⚠	Uses `builder` to retract `value` for `kw` on entity `entid`.
entity_builder_retract_keyword ^⚠	Uses `builder` to retract `value` for `kw` on entity `entid`.
entity_builder_retract_long ^⚠	Uses `builder` to retract `value` for `kw` on entity `entid`.
entity_builder_retract_ref ^⚠	Uses `builder` to retract `value` for `kw` on entity `entid`.
entity_builder_retract_string ^⚠	Uses `builder` to retract `value` for `kw` on entity `entid`.
entity_builder_retract_timestamp ^⚠	Uses `builder` to retract `value` for `kw` on entity `entid`.
entity_builder_retract_uuid ^⚠	Uses `builder` to retract `value` for `kw` on entity `entid`.
entity_builder_transact ^⚠	Transacts all the assertions and retractions that have been performed using this builder.
in_progress_builder ^⚠	Creates a builder using the in progress transaction to allow for programmatic assertion of values.
in_progress_builder_add_boolean ^⚠	Uses `builder` to assert `value` for `kw` on entity `entid`.
in_progress_builder_add_double ^⚠	Uses `builder` to assert `value` for `kw` on entity `entid`.
in_progress_builder_add_keyword ^⚠	Uses `builder` to assert `value` for `kw` on entity `entid`.
in_progress_builder_add_long ^⚠	Uses `builder` to assert `value` for `kw` on entity `entid`.
in_progress_builder_add_ref ^⚠	Uses `builder` to assert `value` for `kw` on entity `entid`.
in_progress_builder_add_string ^⚠	Uses `builder` to assert `value` for `kw` on entity `entid`.
in_progress_builder_add_timestamp ^⚠	Uses `builder` to assert `value` for `kw` on entity `entid`.
in_progress_builder_add_uuid ^⚠	Uses `builder` to assert `value` for `kw` on entity `entid`.
in_progress_builder_commit ^⚠	Transacts and commits all the assertions and retractions that have been performed using this builder.
in_progress_builder_destroy ^⚠
in_progress_builder_retract_boolean ^⚠	Uses `builder` to retract `value` for `kw` on entity `entid`.
in_progress_builder_retract_double ^⚠	Uses `builder` to retract `value` for `kw` on entity `entid`.
in_progress_builder_retract_keyword ^⚠	Uses `builder` to retract `value` for `kw` on entity `entid`.
in_progress_builder_retract_long ^⚠	Uses `builder` to retract `value` for `kw` on entity `entid`.
in_progress_builder_retract_ref ^⚠	Uses `builder` to retract `value` for `kw` on entity `entid`.
in_progress_builder_retract_string ^⚠	Uses `builder` to retract `value` for `kw` on entity `entid`.
in_progress_builder_retract_timestamp ^⚠	Uses `builder` to retract `value` for `kw` on entity `entid`.
in_progress_builder_retract_uuid ^⚠	Uses `builder` to retract `value` for `kw` on entity `entid`.
in_progress_builder_transact ^⚠	Transacts all the assertions and retractions that have been performed using this builder.
in_progress_commit ^⚠	Commit all the transacts that have been performed using this in progress transaction.
in_progress_destroy ^⚠
in_progress_entity_builder_from_entid ^⚠	Creates a builder for an entity with `entid` using the in progress transaction to allow for programmatic assertion of values for that entity.
in_progress_entity_builder_from_temp_id ^⚠	Creates a builder for an entity with `tempid` using the in progress transaction to allow for programmatic assertion of values for that entity.
in_progress_rollback ^⚠	Rolls back all the transacts that have been performed using this in progress transaction.
in_progress_transact ^⚠	Perform a single transact operation using the current in progress transaction. Takes edn as a string to transact.
query_builder_bind_boolean ^⚠	Binds a TypedValue::Boolean to a Variable with the given name.
query_builder_bind_double ^⚠	Binds a TypedValue::Double to a Variable with the given name.
query_builder_bind_kw ^⚠	Binds a TypedValue::Ref to a Variable with the given name. Takes a keyword as a c string in the format `:namespace/name` and converts it into an NamespacedKeyworf.
query_builder_bind_long ^⚠	Binds a TypedValue::Long to a Variable with the given name.
query_builder_bind_ref ^⚠	Binds a TypedValue::Ref to a Variable with the given name.
query_builder_bind_ref_kw ^⚠	Binds a TypedValue::Ref to a Variable with the given name. Takes a keyword as a c string in the format `:namespace/name` and converts it into an NamespacedKeyworf.
query_builder_bind_string ^⚠	Binds a TypedValue::String to a Variable with the given name.
query_builder_bind_timestamp ^⚠	Binds a TypedValue::Instant to a Variable with the given name. Takes a timestamp in microseconds.
query_builder_bind_uuid ^⚠	Binds a TypedValue::Uuid to a Variable with the given name. Takes a `UUID` as a byte slice of length 16. This maps directly to the `uuid_t` C type.
query_builder_destroy ^⚠
query_builder_execute ^⚠	Executes a query and returns the results as a Rel.
query_builder_execute_coll ^⚠	Executes a query and returns the results as a Coll.
query_builder_execute_scalar ^⚠	Executes a query and returns the results as a Scalar.
query_builder_execute_tuple ^⚠	Executes a query and returns the results as a Tuple.
row_at_index ^⚠	Returns the value at the provided `index` as a `Vec<ValueType>`. If there is no value present at the `index`, a null pointer is returned.
rust_c_string_destroy ^⚠
store_begin_transaction ^⚠	Starts a new transaction to allow multiple transacts to be performed together. This is more efficient than performing a large set of individual commits.
store_cache_attribute_bi_directional ^⚠	Adds an attribute to the cache. `store_cache_attribute_bi_directional` caches entity in both available directions, forward and reverse.
store_cache_attribute_forward ^⚠	Adds an attribute to the cache. `store_cache_attribute_forward` caches values for an attribute keyed by entity (i.e. find values and entities that have this attribute, or find values of attribute for an entity)
store_cache_attribute_reverse ^⚠	Adds an attribute to the cache. `store_cache_attribute_reverse` caches entities for an attribute keyed by value. (i.e. find entities that have a particular value for an attribute).
store_destroy ^⚠
store_entid_for_attribute ^⚠	Returns the Entid associated with the `attr` as `:namespace/name`.
store_entity_builder_from_entid ^⚠	Starts a new transaction and creates a builder for an entity with `entid` using the transaction to allow for programmatic assertion of values for that entity.
store_entity_builder_from_temp_id ^⚠	Starts a new transaction and creates a builder for an entity with `tempid` using the transaction to allow for programmatic assertion of values for that entity.
store_in_progress_builder ^⚠	Starts a new transaction and creates a builder using the transaction to allow for programmatic assertion of values.
store_open	A store cannot be opened twice to the same location. Once created, the reference to the store is held by the caller and not Rust, therefore the caller is responsible for calling `store_destroy` to release the memory used by the Store in order to avoid a memory leak.
store_query ^⚠	Creates a QueryBuilder from the given store to execute the provided query.
store_register_observer ^⚠	Registers a TxObserver with the `key` to observe changes to `attributes` on this `store`. Calls `callback` is a relevant transaction occurs.
store_transact ^⚠	Performs a single transaction against the store.
store_unregister_observer ^⚠	Unregisters a TxObserver with the `key` to observe changes on this `store`.
store_value_for_attribute ^⚠	Returns a pointer to the the Binding associated with the `attribute` as `:namespace/name` for the given `entid`. If there is a value for that `attribute` on the entity with id `entid` then the value is returned. If there no value for that `attribute` on the entity with id `entid` but the attribute is value, then a null pointer is returned. If there is no Attribute in the Schema for the given `attribute` then a null pointer is returned and an error is stored in is returned in `error`,
tx_change_list_entry_at ^⚠	Returns the value at the provided `index` as a TransactionChange .
tx_report_destroy ^⚠
tx_report_entity_for_temp_id ^⚠	Fetches the Entid assigned to the `tempid` during the transaction represented by the given TxReport.
tx_report_get_entid ^⚠	Fetches the `tx_id` for the given TxReport`.
tx_report_get_tx_instant ^⚠	Fetches the `tx_instant` for the given TxReport.
typed_value_destroy ^⚠
typed_value_into_boolean ^⚠	Consumes a Binding and returns the value as a boolean represented as an `i32`. If the value of the boolean is `true` the value returned is 1. If the value of the boolean is `false` the value returned is 0.
typed_value_into_double ^⚠	Consumes a Binding and returns the value as a `f64`.
typed_value_into_entid ^⚠	Consumes a Binding and returns the value as an Entid.
typed_value_into_kw ^⚠	Consumes a Binding and returns the value as an keyword C `String`.
typed_value_into_long ^⚠	Consumes a Binding and returns the value as a C `long`.
typed_value_into_string ^⚠	Consumes a Binding and returns the value as a C `String`.
typed_value_into_timestamp ^⚠	Consumes a Binding and returns the value as a microsecond timestamp.
typed_value_into_uuid ^⚠	Consumes a Binding and returns the value as a UUID byte slice of length 16.
typed_value_list_destroy ^⚠
typed_value_list_into_iter ^⚠	Consumes the `Vec<Binding>` and returns an iterator over the values.
typed_value_list_iter_destroy ^⚠
typed_value_list_iter_next ^⚠	Returns the next value in the `iter` as a Binding. If there is no value next value, a null pointer is returned.
typed_value_result_set_destroy ^⚠
typed_value_result_set_into_iter ^⚠	Consumes the `RelResult<Binding>` and returns an iterator over the values.
typed_value_result_set_iter_destroy ^⚠
typed_value_result_set_iter_next ^⚠	Returns the next value in the `iter` as a `Vec<ValueType>`. If there is no value next value, a null pointer is returned.
typed_value_value_type ^⚠	Returns the ValueType of this Binding.
uuid_destroy ^⚠
value_at_index ^⚠	Returns the value at the provided `index` as a Binding. If there is no value present at the `index`, a null pointer is returned.
value_at_index_into_boolean ^⚠	Returns the value of the Binding at `index` as a boolean represented by a `i32`. If the value of the `boolean` is `true` then the value returned is 1. If the value of the `boolean` is `false` then the value returned is 0.
value_at_index_into_double ^⚠	Returns the value of the Binding at `index` as an `f64`.
value_at_index_into_entid ^⚠	Returns the value of the Binding at `index` as an Entid.
value_at_index_into_kw ^⚠	Returns the value of the Binding at `index` as a keyword C `String`.
value_at_index_into_long ^⚠	Returns the value of the Binding at `index` as a `long`.
value_at_index_into_string ^⚠	Returns the value of the Binding at `index` as a C `String`.
value_at_index_into_timestamp ^⚠	Returns the value of the Binding at `index` as a microsecond timestamp.
value_at_index_into_uuid ^⚠	Returns the value of the Binding at `index` as a UUID byte slice of length 16.

Type Definitions

BindingIterator
BindingListIterator
Entid	Represents one entid in the entid space.