Jetstream C/C++ interface
The libjetstream
crate provides an interface for using Jetstream from C/C++.
It is based in the c-interface
from Slipstream.
Example
The example
directory contains an example C++ program that uses Jetstream. This approach could also be used with
Python, Java, and some other languages.
To test the interface run:
make -C example all check
The example involves the following files:
lib.rs
is a wrapper file for accessing the Jetstream API from C. It deals with use ofstructs
and other types in the Jetstream API which are not directly compatible with the C interface. It maintains a list of activeEnocder
andDecoder
objects, so that the C code does not need to keep track of these. The C code accesses and interacts with these objects by passing UUIDs. This approach is basic, and it is up to the caller to ensure that duplicate UUIDs are not provided.main.cpp
provides an example of how to use Jetstream from C/C++, for both encoding and decoding. In particular, it shows how to format arguments and return values for the API functions. The example includes two separate tests: 1) batch encoding of an entire message, and 2) iterative sample-by-sample encoding. Batch encoding is more efficient due to fewer function calls, but it is only possible if all data samples are available. The iterative approach might be suitable for streaming of data in real-time. Note that most of the code in this file is for managing and monitoring tests, and the main parts of interest are thejetstream_*
function calls.jetstream.h
is generated by thecargo build
command and defines the C/C++ API.target/release/libcjetstream.so
is the object file generated bycargo build --profile release
.
Note that C++ is used in the example only for accurate timing using std::chrono
, but the approach should be suitable
for integrating with C and C++ code. The build script could use gcc
instead of g++
for pure C code.
Example code output
After running make all check
, the output similar to the following should be printed to the shell:
using Rust lib from C/C++
*** 1. perform encoding of all samples ***
samples encoded: 4000, length: 46474 bytes
compression efficiency: 9.08% of original size
decoding successful
total duration: 2.18 ms
encode: 0.99 ms
decode: 0.97 ms
decode with processing: 1.19 ms
*** 2. perform iterative encoding of samples ***
samples encoded: 4000, length: 46490 bytes
compression efficiency: 9.08% of original size
decoding successful
total duration: 2.23 ms
encode: 1.16 ms
decode: 0.89 ms
decode with processing: 1.08 ms
License and Copyright
// Copyright (c) 2021 Synaptec Ltd
// Copyright (c) 2022 Richard Lincoln
//
// This program is free software: you can redistribute it and/or
// modify it under the terms of the GNU Affero General Public License
// as published by the Free Software Foundation, either version 3 of
// the License, or (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
// See the GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public
// License along with this program.
// If not, see <https://www.gnu.org/licenses/>.
The original Go version is available under the MIT license. If you are interested in alternative licensing arrangements please get in contact.