/libjetstream

C API for Jetstream using Rust FFI

Primary LanguageC++GNU Affero General Public License v3.0AGPL-3.0

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 of structs and other types in the Jetstream API which are not directly compatible with the C interface. It maintains a list of active Enocder and Decoder 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 the jetstream_* function calls.
  • jetstream.h is generated by the cargo build command and defines the C/C++ API.
  • target/release/libcjetstream.so is the object file generated by cargo 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.