This crate implements the FFI for ClockBound. It builds into the libclockbound C library that an application can use to communicate with the ClockBound daemon.

Usage

clock-bound-ffi requires ClockBound daemon to be running to work.

See ClockBound daemon documentation for installation instructions.

Building

Run the following to build the source code of this crate:

cargo build --release

The build will produce files libclockbound.a and libclockbound.so.

# Copy header file `clockbound.h` to directory `/usr/include/`.
sudo cp clock-bound-ffi/include/clockbound.h /usr/include/

# Copy library files `libclockbound.a` and `libclockbound.so` to
# directory `/usr/lib/`.
sudo cp target/release/libclockbound.a target/release/libclockbound.so /usr/lib/

C example programs

Source code of a runnable C example programs can be found at ../examples/client/c.

This directory contains the source code for example programs in C that show how to obtain error bounded timestamps from the ClockBound daemon. The example programs make use of the libclockbound C library that is produced by clock-bound-ffi.

Prerequisites

• gcc is required for compiling C source code files. Use following command to install it if you don't have it:

  sudo yum install gcc
  

• The ClockBound daemon must be running for the example to work. See the ClockBound daemon documentation for details on how to get the ClockBound daemon running.

• libclockbound library is required for the example to work, as per instructions above.

• Update your ldconfig cache or specify the directories to be searched for shared libraries in the LD_LIBRARY_PATH. Add following to your shell configuration file. See .zshrc example:

  vim ~/.zshrc
  
  # Add following line to the shell configuration file
  export LD_LIBRARY_PATH=/usr/lib
  
  # Use updated shell configuration
  source ~/.zshrc
  

Running

• Run the following command to compile example C source code files.

  # From top-level directory cd into src directory that contains examples in C.
  cd examples/client/c/src
  
  # Compile the C source code files.
  gcc clockbound_now.c -o clockbound_now -I/usr/include -L/usr/lib -lclockbound
  gcc clockbound_loop_forever.c -o clockbound_loop_forever -I/usr/include -L/usr/lib -lclockbound
  

• Run the following command to run the C example programs.

  # Run the `clockbound_now` program.
  ./clockbound_now
  
  # The output should look something like the following:
  When clockbound_now was called true time was somewhere within 1709854392.907495824 and 1709854392.908578628 seconds since Jan 1 1970. The clock status is SYNCHRONIZED.
  It took 9.428327416 seconds to call clock bound 100000000 times (10606335 tps).
  

  # Run the `clockbound_loop_forever` program.
  ./clockbound_loop_forever
  
  # The output should look something like the following:
  When clockbound_now was called true time was somewhere within 1741187470.034504209 and 1741187470.035652589 seconds since Jan 1 1970. The clock status is SYNCHRONIZED (1).
  When clockbound_now was called true time was somewhere within 1741187471.034596805 and 1741187471.035746587 seconds since Jan 1 1970. The clock status is SYNCHRONIZED (1).
  When clockbound_now was called true time was somewhere within 1741187472.034682964 and 1741187472.035834148 seconds since Jan 1 1970. The clock status is SYNCHRONIZED (1).
  
  # To quit the example program, press CTRL-C.
  

• Clean up

  rm ./clockbound_now
  rm ./clockbound_loop_forever
  

Security

See CONTRIBUTING for more information.

License

Licensed under the Apache 2.0 license.