NEWS (24-Aug-2020)
Version 0.0.3
. Enhanced the management of the tick period
. Added internal utility tdw_get_ticks() for debug purposes
============================================
Timers on Delta Wheel
(TDW)
============================================
CONTENTS OF THIS FILE
=====================
* Introduction
* Maintainers
* Build suites
* Download
* cmake mode
* tdw_setup.sh script
* Build, installation, cleanup
* Tests
* Tests coverage measurement
* Packaging
* Notes about RPM package
* Notes about DEB package
* Documentation
* On line manuals
* Articles
* References
Introduction
============
The current document concerns the 0.0.3 version of the TDW package.
TDW (Timers on Delta Wheel) is an simple API to manage timers. It is a
combination of delta list and timer wheel algorithms. Upon timer expiration
a user defined callback is invoked.
The API is delivered as a C language library (libtdw.so) distributed under
the GNU LGPL license.
For a description of the software, look at the online manuals once the software
is unpacked.
Maintainers
===========
To report a bug or design enhancement, please contact:
Rachid Koucha <rachid dot koucha at gmail dot com>
Build suites
============
TDW is built with CMAKE.
Download
========
* The source tree of this package can be downloaded from:
https://sourceforge.net/projects/tdwheel
tdw_setup.sh script
===================
This script is a swiss army knife to make several things:
$ ./tdw_setup.sh -h
Usage:
tdw_setup.sh [-b browser] [-c] [-T|-C] [-d install_dir]
[-B] [-I] [-U] [-A] [-P RPM|DEB|TGZ|STGZ] [-h]
-b : Browser's pathname to display the test coverage HTML results
-c (*): Cleanup built objects
-C : Launch test coverage measurement
-T : Launch regression tests
-d : Installation directory (default: /usr/local)
-P (*): Generate RPM|DEB|TGZ|STGZ packages
-B : Build the software
-I (*): Install the software
-U (*): Uninstall the software
-A : Generate an archive of the software (sources)
-h : this help
(*) Super user rights required
Note that some options require super user priviledges to run. Use "sudo" for example.
Build, installation, cleanup
============================
From the top level of the source code, it is possible to use cmake directly:
$ cmake .
...
$ make
...
$ sudo make install
...
But it is also possible to use tdw_setup.sh script:
* For a complete installation in the default /usr/local subtree:
$ sudo ./tdw_setup.sh -I
* To uninstall the software:
$ sudo ./tdw_setup.sh -U
* To cleanup every generated files to go back to original source tree:
$ sudo ./tdw_setup.sh -c
Tests
=====
The regression tests are based on CHECK library. The latter must be installed
prior to launch the tests (e.g. sudo apt install check).
. To trigger the regression tests for the whole software:
$ ./tdw_setup.sh -T
... Wait several long seconds ...
Configuring TDW installation in /usr/local...
-- Building TDW version 0.0.3
'gzip' program found in /usr/bin/gzip
[...]
100%: Checks: 8, Failures: 0, Errors: 0
Tests coverage measurement
==========================
. To trigger test coverage measurement (with a display of the result in firefox):
$ ./tdw_setup.sh -C -b firefox
... Wait several long seconds ...
Overall coverage rate:
lines......: 89.5% (428 of 478 lines)
functions..: 100.0% (14 of 14 functions)
Lcov code coverage info report saved in all_coverage.info
Open ./all_coverage/index.html in your browser to view the coverage report.
[100%] Built target all_coverage
. If the test suite is run with super user rights, the test suite configures
the service's underlying thread with a real-time priority. This reduces the
latency. This also slightly increases the test coverage:
$ sudo ./tdw_setup.sh -C -b firefox
...
Overall coverage rate:
lines......: 91.0% (435 of 478 lines)
functions..: 100.0% (14 of 14 functions)
Lcov code coverage info report saved in all_coverage.info
Open ./all_coverage/index.html in your browser to view the coverage report.
[100%] Built target all_coverage
Packaging
=========
. To make a source package, use the -A option:
$ ./tdw_setup.sh -A
This makes a TGZ file of the complete source tree: tdw_src-0.0.3.tgz
. We provide the ability to generate Debian (DEB), Red-Hat Package Manager (RPM),
Tar GZipped (TGZ) and Self Extracting Tar GZipped (STGZ) binary packages.
. To build the packages (TGZ, DEB, RPM...):
$ sudo ./tdw_setup.sh -c -P tgz -P rpm -P deb -P stgz
This makes the following binary packages:
. tdw-dev_0.0.3_amd64.deb (DEB)
. tdw-dev-0.0.3-1.x86_64.rpm (RPM)
. tdw-0.0.3-Linux-dev.tar.gz (TGZ)
. tdw-0.0.3-Linux-dev.sh (STGZ)
Notes about RPM package
=======================
. Use the following to get information on a package file:
$ rpm -qp --info tdw-dev-0.0.3-1.x86_64.rpm
Name : tdw
Version : 0.0.3
Release : 1
Architecture: x86_64
Install Date: (not installed)
Group : unknown
Size : 625231
License : GPL/LGPL
Signature : (none)
Source RPM : tdw-dev-0.0.3-1.src.rpm
Build Date : lun. 29 avril 2019 09:43:18 CEST
Build Host : pc-work
Relocations : /usr/local
Vendor : Rachid Koucha
URL : https://sourceforge.net/projects/tdwheel
Summary : TDW (Timers based on Delta Wheels)
Description :
Timer library based on the combination of delta list and Timer wheel algorithms
. Use the following to get the pre/post-installation scripts in a package file:
$ rpm -qp --scripts tdw-dev-0.0.3-1.x86_64.rpm
preinstall program: /bin/sh
postinstall scriptlet (using /bin/sh):
#!/bin/sh
INSTALL_PREFIX=/usr/local
FILE=${INSTALL_PREFIX}/lib/libtdw.so
chmod 666 ${FILE}
chown root ${FILE}
chgrp root ${FILE}
FILE=${INSTALL_PREFIX}/share/man/man3/tdw.3.gz
...
. Use following to list the files for an INSTALLED package:
$ rpm -ql tdw
...
. Use following to list the files in a package file:
$ rpm -ql tdw-dev-0.0.3-1.x86_64.rpm
/usr/local
/usr/local/include
/usr/local/include/tdw.h
/usr/local/lib
/usr/local/lib/libtdw.so
...
. The required package list of an RPM file could be printed with:
$ rpm -qp --requires tdw-dev-0.0.3-1.x86_64.rpm
/bin/sh
...
Notes about DEB package
=======================
. Use the following to get information on a package file:
$ dpkg --info tdw-dev_0.0.3_amd64.deb
new Debian package, version 2.0.
size 21940 bytes: control archive=458 bytes.
255 bytes, 10 lines control
252 bytes, 4 lines md5sums
Architecture: amd64
Description: Timers on Delta Wheel
Homepage: https://sourceforge.net/projects/tdwheel
Maintainer: Rachid Koucha <rachid dot koucha at gmail dot com>
Package: tdw-dev
Priority: optional
Section: devel
Version: 0.0.3
Installed-Size: 85
. Use following to list the files in a package file:
$ dpkg -c tdw-dev_0.0.3_amd64.deb
drwxr-xr-x root/root 0 2020-08-19 14:40 ./usr/
drwxr-xr-x root/root 0 2020-08-19 14:40 ./usr/local/
drwxr-xr-x root/root 0 2020-08-19 14:40 ./usr/local/include/
-r--r--r-- root/root 1892 2020-08-16 23:50 ./usr/local/include/tdw.h
drwxr-xr-x root/root 0 2020-08-19 14:40 ./usr/local/lib/
-r--r--r-- root/root 50240 2020-08-19 14:40 ./usr/local/lib/libtdw.so
drwxr-xr-x root/root 0 2020-08-19 14:40 ./usr/local/share/
drwxr-xr-x root/root 0 2020-08-19 14:40 ./usr/local/share/man/
drwxr-xr-x root/root 0 2020-08-19 14:40 ./usr/local/share/man/man3/
-r--r--r-- root/root 1137 2020-08-19 14:40 ./usr/local/share/man/man3/tdw.3.gz
drwxr-xr-x root/root 0 2020-08-19 14:40 ./usr/local/share/man/man5/
-r--r--r-- root/root 617 2020-08-19 14:40 ./usr/local/share/man/man5/tdw.5.gz
. Use following to install the content of a package file:
$ sudo dpkg -i tdw-dev_0.0.3_amd64.deb
Selecting previously unselected package tdw-dev.
(Reading database ... 293770 files and directories currently installed.)
Preparing to unpack tdw-dev_0.0.3_amd64.deb ...
Unpacking tdw-dev (0.0.3) ...
Setting up tdw-dev (0.0.3) ...
Processing triggers for man-db (2.9.1-1) ...
. Use the following to list the installed packages:
$ dpkg -l | grep tdw
ii tdw-dev 0.0.3 amd64 Timers on Delta Wheel
. Use following to uninstall (remove) a package:
$ sudo dpkg -r tdw-dev
(Reading database ... 293779 files and directories currently installed.)
Removing tdw-dev (0.0.3) ...
dpkg: warning: while removing tdw-dev, directory '/usr/local/share/man/man5' not empty so not removed
dpkg: warning: while removing tdw-dev, directory '/usr/local/share/man/man3' not empty so not removed
dpkg: warning: while removing tdw-dev, directory '/usr/local/lib' not empty so not removed
dpkg: warning: while removing tdw-dev, directory '/usr/local/include' not empty so not removed
Processing triggers for man-db (2.9.1-1) ...
====================================================================================================
DOCUMENTATION
=============
On line manuals
===============
. Once tdw is installed, it is possible to access the corresponding manuals with.
The API is described in:
$ man 3 tdw
tdw(3) TIMERS BASED ON DELTA WHEEL tdw(3)
NAME
tdw - User API for timers (version )
SYNOPSIS
#include <tdw.h>
tdw_t tdw_alloc(int type);
int tdw_start(tdw_t timer, unsigned int timeout, void (*user_cbk)(void *), void *user_ctx);
int tdw_stop(tdw_t timer);
int tdw_free(tdw_t timer);
...
The configuration through environment variables is described in:
$ man 5 tdw
tdw(5) Environment variables tdw(5)
NAME
tdw - Environment variables of Timers on Delta Wheel (TDW)
ENVIRONMENT VARIABLES
Timers on Delta Wheel (TDW) comes with a bunch of configuration en-
vironment variables. The available variables are:
...
Articles
========
An article describing the internals of the service will be published soon in GNU/Linux magazine France.
Download Latest Version
tdw_src-0.0.3.tgz (45.0 kB)
