Sturk

Table of Contents

• Quickstart
  • Initialize a broker
  • Create a subscriber
  • Subscribe to a topic
  • Publish to a topic
  • Receive a message
• Portability
• Usage
  • Compile libsturk.a
  • Link to libsturk.a
  • Configuring
• Overview
• Buildsystem
  • C99 support
  • Example configuration
• Glossary

Sturk is a C library that implements the publish-subscribe messaging pattern.

Quickstart

Initialize a broker

StBroker* broker = broker_create(SAMPLE_MESSAGE_API);

Create a subscriber

StSubscriber* sber = subscriber_create(broker);

Subscribe to a topic

subscribe(sber, "test");

Publish to a topic

publish(broker_search(broker, "test"), 5);

Receive a message

msg = subscriber_await(sber);

Portability

• C99 support: gcc -std=c99 -pedantic ....
• CI/CD platforms: ubuntu, macos, windows.
• OSAL.

Usage

Sturk is designed with an intention to be used as a static library. Therefore, the most straightforward approach to compile a program that uses Sturk would be to build in two steps:

1. compile Sturk library,
2. compile the program while linking to Sturk library and its header files.

Note

• By default, the library is built at /path/to/sturk/build/src/libsturk.a.
• Header files are located at /path/to/sturk/include.

Compile libsturk.a

cd /path/to/sturk
make

Link to libsturk.a

cc main.c /path/to/sturk/build/src/libsturk.a -I/path/to/sturk/include

Configuring

To configure the build see buildsystem.

To choose an OS or to add support for an OS see also osal.

Note

By default multithreading is not supported.

Overview

Sturk consists of several modules with dependencies as shown in the Modules hierarchy diagram.

Modules hierarchy

The role of each module, hyperlink to its documentation and the location of its public header files are gathered in the Modules table. The ordering of the table corresponds to the modules hierarchy.

Table: Modules

#	Module	Provides	Include subdirectory
1	broker	publish-subscribe utility	st (sturk)
2	algo	memory pool; waiting queue; dictionary	st (sturk)
3	logger	logging to stdout/stderr/file	st/logger (sturk/logger)
4	osal	memory allocator; filesystem; thread sync.	st/os (sturk/os)
5	basis	arena	st (sturk)
6	vertegs	subroutines for operating on graphs	vertegs

Buildsystem

The build is configured with a single yaml file. Before running make the configuration file must be passed to the configure.sh script in order to generate a makefile.

mkdir build
cd build
 
# generate makefile
/path/to/sturk/tools/configure.sh /path/to/config.yaml
 
# build default target - libsturk.a
make

All possible build variables can be found inside olconf.yaml files from the src directory. The configuration is processed by olconf.py scripts.

C99 support

Configuring with cver: "gnu" will pass -std=gnu11 to the compiler while cver: "iso" will pass -std=c99 -pedantic instead.

See src/olconf.py.

if settings['cver'] == 'gnu':
    olvars.append('sturk_EXTRA_CFLAGS', '-std=gnu11')
elif settings['cver'] == 'iso':
    olvars.append('sturk_EXTRA_CFLAGS', '-std=c99')
    olvars.append('sturk_EXTRA_CFLAGS', '-pedantic')
else:
    olvars.fail('Unknown cver: ' + settings['cver'] + '.')

Example configuration

As an example see configs/iso/olconf.yaml and compare it to src/olconf.yaml.

The following

/path/to/sturk/tools/configure.sh /path/to/sturk/configs/iso/olconf.yaml

would overwrite the default configuration from src/olconf.yaml:

• cver: "gnu",
• build_type: "release";

with the configuration from configs/iso/olconf.yaml:

• cver: "iso",
• build_type: "coverage".

Glossary

Table: Glossary

Term	Description
OSAL	Operating System Abstraction Layer
API	Application Programming Interface
cirq	short name for doubly linked circular list