Crate cobia

Expand description

§Crate cobia - RUST Language binding for CO-LaN’s COBIA middleware.

CAPE-OPEN consists of a series of specifications to expand the range of application of process simulation technologies. The CAPE-OPEN specifications specify a set of software interfaces that allow plug and play inter-operability between a given process modelling environment (PME) and a third-party process modelling component (PMC).

The CAPE-OPEN specifications are supported by the non-profit organization CO-LaN: http://www.colan.org

The COBIA middle-ware is a platform independent object model and request broker implementation to facilitate the inter-operation of CAPE-OPEN compliant PMEs and PMCs.

This create provides the following:

Safe Rust wrappers around the raw C FFI bindings to COBIA’s API routines
Rust based implementation of the CAPE-OPEN data types
Rust based wrappers around externally implemented CAPE-OPEN data types
A Rust code generator utility that utilizes COBIA’s public type API to generate Rust bindings
Rust traits representing COBIA interfaces
Rust native implementations of COBIA based interfaces using objects that provide the Rust traits
Smart pointers to COBIA objects
Rust definitions for externall implemented COBIA objects
Macros to make implementing CAPE-OPEN components in Rust

§Prerequisites

To compile against this create, the following prerequisites must be installed:

The COBIA SDK (available for download from https://colan.repositoryhosting.com/trac/colan_cobia/downloads
The required ingredients for bindgen, including a valid CLANG installation, see https://rust-lang.github.io/rust-bindgen/requirements.html

This package uses bindgen to generate Rust access to the C-API of COBIA. As with most Rust implementations that refer to C/C++ code, all external access is unsafe, and marked as such in the cobia crate itself. Typically one does not need to use the unsafe keyword in implementations that use cobia, with a few exceptions.

§Interface implementation considerations

COBIA is a middle-ware that allows objects implemented in different languages to inter-operate. They do so through the use of reference counted interfaces, much like other middle-wares such as COM or CORBA.

To allow the Rust compiler to check the life time and validity of pointers, interface pointers are passed by reference. A Rust object that implements one or more COBIA interface is allocated on the heap by boxing it as part of its creation. Once the object is boxed, its vTable pointers are initialized to point to the correct memory location. The boxed object is then converted to a raw pointer; this raw pointer is the interface pointer’s ‘me’ member, and is used by the raw interface methods to access the Rust object. The raw interface methods require Rust traits to be implemented on the Rust object, to provide the actual functionality.

Data that requires heap allocations (strings, arrays, …) are handled a little differently. They too have a vTable, but at the design of this crate it was decided not to box the data objects, as the heap allocation for the object itself may well not be needed and may hamper performance.

As a result, it is quite possible, and even likely, for data object implementations to be moved around after its creation. When passed to a foreign function, the vTable for the data object is created on the fly, pointing to where the data object is currently located. The reference to the vTable requires a reference to the data object implementation, so Rust’s life span checking is used to ensure that the data object implementation remains valid during the life span of the vTable, and the vTable remains valid for the duration of the external call.

To further leverage Rust’s safety features, data objects have In and Out versions. The In version cannot be modified by the receiver, whereas the intent of the Out version is exactly to be modified. Functions that require an In data type, can do so by a reference to it. Function that require an Out data type on the other hand, require a mutable reference; this ensures that an Out data object is not modified unexpectedly.

§Rust code generation

To generate Rust bindings for interfaces described by CAPE-OPEN IDL (either in a .cidl file or a library in the COBIA registry), the cidl.exe tool can be used. This tool is part of the current crate. This tool is used during the build process to generate the bindings for the default cape_open and cape_open_1_2 modules, containing all known CAPE-OPEN interfaces in the installed COBIA SDK.

The cidl tool can also be used to generate bindings for custom CAPE-OPEN interfaces; this functionality is currently untested, arising a business case.

§CAPE-OPEN object implementations

To implement a CAPE-OPEN object in rust, one can use the cape_object_implementation macro. This macro takes as arguments the interfaces that are implemented by the object, as well as some optional constructor details.

To implement the entry points for a COBIA dynamic link library, one can use the pmc_entry_points macro.

The reader is directed to the Salt Water Property Package example and the Distillation Shortcut Unit Operation examples in the repository for further details.

Extenally implemented COBIA objects are accessed through smart pointers; an interface specific smart pointer is generated for each known COBIA interface, along with the Rust methods that represent the interface methods.

§Acknowledgements

This package uses process_path, to get the path of the currently executing process or dynamic library, (C) Copyright Wesley Wiser and process_path contributors

This package uses bindgen, to automatically generates Rust FFI bindings to C and C++ libraries, (C) Jyun-Yan You

Re-exports§

pub use C::CapeBoolean;
pub use C::CapeReal;
pub use C::CapeInteger;
pub use C::CapeResult;
pub use C::CapeCharacter;
pub use C::CapeByte;
pub use C::CapeEnumeration;
pub use cape_value_impl::CapeValueImpl;
pub use cape_value_impl::CapeValueContent;
pub use C::CapeUUID;

Modules§

C
cape_array 🔒
cape_array_boolean 🔒
cape_array_byte 🔒
cape_array_enumeration 🔒
cape_array_integer 🔒
cape_array_object_vec 🔒
cape_array_real 🔒
cape_array_real_scalar 🔒
cape_array_slice 🔒
cape_array_string 🔒
cape_array_value 🔒
cape_array_vec 🔒
cape_data_from_provider 🔒
cape_data_traits 🔒
cape_error 🔒
cape_error_impl 🔒
cape_object 🔒
cape_object_impl 🔒
cape_open
cape_open_1_2
cape_pmc_enumerator 🔒
cape_pmc_registration_details 🔒
cape_registrar 🔒
cape_registry_key 🔒
cape_registry_key_writer 🔒
cape_registry_writer 🔒
cape_result_value 🔒
cape_smart_pointer 🔒
cape_string 🔒
cape_string_const 🔒
cape_string_impl 🔒
cape_string_map 🔒
cape_type_library_details 🔒
cape_type_library_enumerator 🔒
cape_value 🔒
cape_value_impl
cape_window_id 🔒
cobia_collection 🔒
cobia_enums 🔒
cobia_error 🔒
cobia_identification 🔒
cobia_pmc_helpers 🔒
prelude

Macros§

pmc_entry_points: Generate PMC entry points

Structs§

CapeArrayBooleanInFromProvider: CapeArrayBooleanInFromProvider
CapeArrayBooleanOutFromProvider: CapeArrayBooleanOutFromProvider
CapeArrayByteInFromProvider: CapeArrayByteInFromProvider
CapeArrayByteOutFromProvider: CapeArrayByteOutFromProvider
CapeArrayEnumerationIn: CapeArrayEnumerationIn wraps an ICapeArrayEnumeration interface pointer.
CapeArrayEnumerationInFromProvider: CapeArrayEnumerationInFromProvider
CapeArrayEnumerationOut: CapeArrayEnumerationOut wraps an ICapeArrayEnumeration interface pointer.
CapeArrayEnumerationOutFromProvider: CapeArrayEnumerationOutFromProvider
CapeArrayIn: CapeArrayIn wraps an ICapeArray interface pointer.
CapeArrayIntegerInFromProvider: CapeArrayIntegerInFromProvider
CapeArrayIntegerOutFromProvider: CapeArrayIntegerOutFromProvider
CapeArrayObjectVec: Base implementation for CapeArrayStringVec and CapeArrayValueVec
CapeArrayOut: CapeArrayOut wraps an ICapeArray interface pointer.
CapeArrayRealInFromProvider: CapeArrayRealInFromProvider
CapeArrayRealOutFromProvider: CapeArrayRealOutFromProvider
CapeArrayRealScalar: Scalar based CapeArrayRealOut implementation
CapeArraySlice: Slice based implementation of ICapeArray
CapeArrayStringIn: CapeArrayStringIn wraps an ICapeArrayString interface pointer in a read-only manner
CapeArrayStringInFromProvider: CapeArrayStringInFromProvider
CapeArrayStringOut: CapeArrayStringOut wraps an ICapeArrayString interface pointer.
CapeArrayStringOutFromProvider: CapeArrayStringOutFromProvider
CapeArrayValueIn: CapeArrayValueIn wraps an ICapeArrayValue interface pointer in a read-only manner
CapeArrayValueInFromProvider: CapeArrayValueInFromProvider
CapeArrayValueOut: CapeArrayValueOut wraps an ICapeArrayValue interface pointer.
CapeArrayValueOutFromProvider: CapeArrayValueOutFromProvider
CapeArrayVec: Vector based implementation of ICapeArray
CapeError: Error description from CAPE-OPEN object
CapeErrorImpl: CAPE-OPEN Error object implementation
CapeLibraryDetails: CapeLibraryDetails provides details about a registered COBIA type library
CapeObject: Generic Cape Object smart pointer
CapeObjectData: Internal data for CAPE-OPEN object implementations.
CapeOpenMap: Class to store a platform dependent string encoding for use in case insensitive hash maps or for use of case insensitive comparisons.
CapePMCCreationFlags
CapePMCEnumerator: Enumerator for all registered PMCs.
CapePMCRegistrationDetails: PMC registration details
CapePMCRegistrationFlags
CapePMCServiceTypeIterator: CapePMCServiceType iterator
CapeRegistrar: Rust wrapper for ICapePMCRegistrar interface
CapeRegistryKey: A class that provides access to a COBIA registry key in a read-only manner
CapeRegistryKeyWriter: A writable COBIA registry key
CapeRegistryValueTypeIterator: CapeRegistryValueType iterator
CapeRegistryWriter: Opens the COBIA registry for writing
CapeStringConstNoCase: Class to store a platform dependent string encoding for use in case insensitive hash maps or for use of case insensitive comparisons.
CapeStringImpl: Default ICapeString implementation
CapeStringIn: CapeStringIn wraps an ICapeString interface pointer as read-only.
CapeStringInFromProvider: CapeStringInFromProvider
CapeStringOut: CapeStringOut wraps an ICapeString interface pointer.
CapeStringOutFromProvider: CapeStringOutFromProvider
CapeTypeLibraries: Enumerator for all registered type libraries.
CapeValueIn: CapeValueIn wraps a reference to an ICapeValue interface pointer.
CapeValueInFromProvider: CapeValueInFromProvider
CapeValueOut: CapeValueOut wraps an ICapeValue interface pointer.
CapeValueOutFromProvider: CapeValueOutFromProvider
CapeValueTypeIterator: CapeValueType iterator
CobiaIdentification: CobiaIdentification interface smart pointer
PMCInfo: PMCInfo is a struct that contains the information required to register a PMC.

Enums§

COBIAError: A COBIA error, with description
CapePMCServiceType: Service provider types
CapeRegistryValueType: Registry value type
CapeStringHashKey: Class to store a platform dependent string encoding for use in case insensitive hash maps or for use of case insensitive comparisons.
CapeValueType: CapeValue data types

Constants§

Traits§

CapeArrayBooleanProviderIn: Any object that implements this trait can be converted to an ICapeArrayBoolean input argument
CapeArrayBooleanProviderOut: Any object that implements this trait can be converted to an ICapeArrayBoolean output argument
CapeArrayByteProviderIn: Any object that implements this trait can be converted to an ICapeArrayByte input argument
CapeArrayByteProviderOut: Any object that implements this trait can be converted to an ICapeArrayByte output argument
CapeArrayEnumerationProviderIn: Any object that implements this trait can be converted to an ICapeArrayEnumeration input argument
CapeArrayEnumerationProviderOut: Any object that implements this trait can be converted to an ICapeArrayEnumeration output argument
CapeArrayIntegerProviderIn: Any object that implements this trait can be converted to an ICapeArrayInteger input argument
CapeArrayIntegerProviderOut: Any object that implements this trait can be converted to an ICapeArrayInteger output argument
CapeArrayRealProviderIn: Any object that implements this trait can be converted to an ICapeArrayReal input argument
CapeArrayRealProviderOut: Any object that implements this trait can be converted to an ICapeArrayReal output argument
CapeArrayStringProviderIn: Any object that implements this trait can be converted to an ICapeArrayString input argument
CapeArrayStringProviderOut: Any object that implements this trait can be converted to an ICapeArrayString output argument
CapeArrayValueProviderIn: Any object that implements this trait can be converted to an ICapeArrayValue input argument
CapeArrayValueProviderOut: Any object that implements this trait can be converted to an ICapeArrayValue output argument
CapeCreateInstance: CapeCreateInstance is creates an instance of a PMC object. This trait is typically implemented by the cape_object_implementation! macro and only for objects created with the cape_object_implementation! macro, which do not take any arguments for construction.
CapeRegistryKeyReader: Public trait that provides methods to read from the registry key
CapeStringConstProvider: Any object that implements this trait can be compared to any CapeString type object
CapeStringProviderIn: Any object that implements this trait can be converted to an ICapeString input argument
CapeStringProviderOut: Any object that implements this trait can be converted to an ICapeString output argument
CapeValueProviderIn: Any object that implements this trait can be converted to an ICapeValue input argument
CapeValueProviderOut: Any object that implements this trait can be converted to an ICapeValue output argument
ICapeInterfaceImpl: This trait is implemented by all CAPE-OPEN objects.
PMCRegisterationInfo: PMCRegisterationInfo is a trait that must be implemented by a struct that implements a PMC. The trait provides the information required to register the PMC with the COBIA registry.

Functions§

CapeWindowIdFromRaw
CapeWindowIdToRaw
cape_open_cleanup: #COBIA clean-up routine
cape_open_initialize: #COBIA initialization routine
get_cobia_folder: #get COBIA installation folder
get_cobia_language: #get COBIA language
get_cobia_system_data_folder: #get COBIA system data folder
get_cobia_user_data_folder: #get COBIA user data folder
get_cobia_version: #get COBIA version
inproc_service_type: Service function to get in-process service type for current bitness
pmc_info: class factory for a pmc_info object from a CAPE-OPEN object class
register_pmc: register a PMC into the COBIA registry
unregister_pmc: unregister a PMC from the COBIA registry

Type Aliases§

CapeArrayBooleanIn: CapeArrayBooleanIn wraps an ICapeArrayBoolean interface pointer.
CapeArrayBooleanOut: CapeArrayBooleanOut wraps an ICapeArrayBoolean interface pointer.
CapeArrayBooleanSlice: Slice based CapeArrayBooleanIn implementation
CapeArrayBooleanVec: Vector based CapeArrayBooleanOut implementation
CapeArrayByteIn: CapeArrayByteIn wraps an ICapeArrayByte interface pointer.
CapeArrayByteOut: CapeArrayByteOut wraps an ICapeArrayByte interface pointer.
CapeArrayByteSlice: Slice based CapeArrayByteIn implementation
CapeArrayByteVec: Vector based CapeArrayByteOut implementation
CapeArrayEnumerationSlice: Slice based CapeArrayEnumerationIn implementation
CapeArrayEnumerationVec: Vector based CapeArrayEnumerationOut implementation
CapeArrayIntegerIn: CapeArrayIntegerIn wraps an ICapeArrayInteger interface pointer.
CapeArrayIntegerOut: CapeArrayIntegerOut wraps an ICapeArrayInteger interface pointer.
CapeArrayIntegerSlice: Slice based CapeArrayIntegerIn implementation
CapeArrayIntegerVec: Vector based CapeArrayIntegerOut implementation
CapeArrayRealIn: CapeArrayRealIn wraps an ICapeArrayReal interface pointer.
CapeArrayRealOut: CapeArrayRealOut wraps an ICapeArrayReal interface pointer.
CapeArrayRealSlice: Slice based CapeArrayRealIn implementation
CapeArrayRealVec: Vector based CapeArrayRealOut implementation
CapeArrayStringVec: Vector based CapeArrayStringOut implementation
CapeArrayValueVec: Vector based CapeArrayValueOut implementation
CapeWindowId
CobiaCollection: CobiaCollection wraps an ICobiaCollection interface

Attribute Macros§

cape_object_implementation: The cape_object_implementation macro generates the necessary code to implement a COBIA object.
cape_smart_pointer: The cape_smart_pointer macro generates the necessary code to implement a COBIA smart pointer.

Crate cobiaCopy item path