dtk-config

dtk-config is a program that just prints text to standard output.  dtk-config prints information about your DTK installation, like DTK compile options and where DTK files are installed.

In your shell try running the following command:

% dtk-config  

If this failed to run you may need to fix your PATH environment variable.  Here's an example result running on the authors Gentoo GNU/Linux PC using a Gnome Terminal:

Run dtk-config with some of the listed option flags.  Come on! - at least try 'dtk-config --about'.

dtk-config can be your friend when you want information about the DTK installation that you're using.

dtk-floatSliders

% dtk-floatSliders foo --number 6 --scale 3 -180 180 0 --scale 4 -180 180 0 --scale 5 -180 180 0 --labels x y z h p r &
  
% dtk-readFloats foo --queue --count  

These two programs both have the DTK shared memory file "foo" open.  The dtk-floatSliders programs writes to the shared memory file "foo", when you move a slider.  The program dtk-readFloats reads from the file "foo".  All DTK shared memory has an associated file. If you look you'll see there is a file "/tmp/dtkSharedMem/foo" on your computer:

% ls -l /tmp/dtkSharedMem/foo  
-rw-rw-rw-    1 lanceman lanceman     1208 May 14 14:18 /tmp/dtkSharedMem/foo

DTK shared memory files are a regular data file type.  This file contains values of the users data in addition to information associated with queuing, counting, time-stamping and network connectivity.  Since it is a regular file you can build a structured name space with directories and symlinks with DTK shared memory files.

More

dtk-floatScope

% dtk-floatScope foo --scale foo 3 -180 180 --scale foo 4 -180 180 --scale foo 5 -180 180 &  

Reminder: run this program (dtk-floatScope) with the '--help' option too. 

Move some of the sliders.  Though the dtk-floatSliders programs can only write one float at a time, the dtk-floatScope reads all 6 floats at each little X that is plotted.  The dtk-floatScope program can read multiple DTK shared memory files so the '--scale' option requires the additional shared memory file name ("foo") argument to tell it which shared memory file to scale.

If you have never used an oscilloscope before the utility of this program may pass you by, but if you have you may notice that this program crys out for more options and controls.  dtk-floatScope will be a growing program for some time to come.  dtk-floatScope in it's current implementation is useful for debugging interactive input devices and interactive dynamics programs.

Now try running another copy of the dtk-floatScope.  Notice the two dtk-floatScope programs do not interfere with each other in any observable way.

dtk-gnomonDisplay

% dtk-gnomonDisplay foo &  

Move some of the sliders.  dtk-gnomonDisplay is just another float array displayer, like dtk-floatScope, but is very specific in how it interprets the float data.  dtk-gnomonDisplay interprets the float data array as displacement positions x, y, and z, and rotations about z (heading, H), rotations about x (pitch, P), and rotations about y (roll, R).  It's a quick and easy way to see if something is moving like you hoped it was.

dtk-server

dtk-server runs to provide services.  These service provide the needed open files to get interrupts from.  Most DTK services come in the form of run-time loadable dynamics shared objects (DSOs), we call DTK DSO services.  Most DTK services tend to be very hardware specific, like for example a 6 degree-of-freedom tracker service.  The hello DTK DSO service is a very simple example service that reads from standard input and then writes to DTK shared memory.

In one shell run:

% dtk-server hello  

In another shell run:

% dtk-readStrings hello  

Type in the first shell and hit enter.  Your text is read in by the dtk-server and then written to DTK shared memory file "hello".  The second program reads the shared memory and then prints to standard output.  The connection between these two programs is DTK shared memory.

In yet another shell run:

% dtk-readStrings hello --queue  

Type into the dtk-server window again.  The difference between the two dtk-readStrings programs is that one is reading from queued shared memory and the other is periodically polling and writing to standard output the last thing written in the shared memory.  The second "queue reading" dtk-readStrings is not synchronized with the shared memory writing program dtk-server, but it gives that appearance because it is checking the queue at a high rate. 

In one more shell run:

% dtk-readStrings hello --queue --time-stamp  

Type into the dtk-server window some more.  This version of dtk-readStrings reads from a time stamped, and queued DTK shared memory file called "hello".  It's the same "hello" shared memory file, but it just got a little larger when you ran this recent dtk-readString.  Programs that write to DTK shared memory don't need to know if the shared memory is queued or not, time stamped or not, and count stamped or not.  Typically it's the data reading programs choose to decide if shared memory data is queued, time stamped, or count stamped.  Shared memory queuing and time stamping are used by dtk-floatScope to give the apparence of synchronous data plotting, in the example above.

DTK Remote Shared Memory

If you have two or more networked computers connecting them is easy.

Leave all the "hello" reading and writing programs running, dtk-server and dtk-readStrings.  On your computer you should already have two windows open (if not run the following commands on your computer).  On another computer networked to the one you are currently using run:

% dtk-server hello 
% dtk-readStrings --queue hello 

Now you should have two windows open on both machines.  One window with "type here ==>" and one that is blank (unless you already typed something in).

Now you can connect them.  On the one of the machines run:

% dtk-connectRemoteSharedMem hello "name of other machine on network" 
example % dtk-connectRemoteSharedMem hello rabbit.vt.edu

Voila! The two machines are connected. Try typing something in either of the "type here ==>" windows.

If want to simulate a connecting computers on a network on one machine.

We'll use them as the local shared memory users and we'll make them share the "hello" string across the loop-back network.  The loop-back network is kind of like a pretend IP network that has end points (ports) that are both on the same machine and does not use networking hardware.  Among other things, it's can be used to let IP networked programs run on one machine that is not on a network.

If your using the bash or ksh shell do not run the programs with the tcsh% prompt, or if your running a tcsh or csh shell do not run the programs with the bash% prompt. 

Fire up two more shell windows.  We call these the "remote shells".  First we need to set some DTK environment variables.  In both remote shells run:

bash% export DTK_PORT=2345  
bash% export DTK_CONNECTION=localhost:2345  
bash% export DTK_SHAREDMEM_DIR=/tmp/dtkSharedMem2345  

or

tcsh% setenv DTK_PORT 2345  
tcsh% setenv DTK_CONNECTION localhost:2345  
tcsh% setenv DTK_SHAREDMEM_DIR /tmp/dtkSharedMem2345  

Now run in one of the shells:

% dtk-config --env  

looky then

% dtk-printEnv  

The 'dtk-config --env' tells you all about DTK environment variables.  'dtk-config --env' lists all environment variables used by the DTK API and DTK programs.  dtk-printEnv just prints the current DTK environment variables (as you knew by running 'dtk-printEnv --help', right!).

Run one in each shell the following:

% dtk-server hello  
% dtk-readStrings --queue hello  

As before type into the first shell.  Nothing new here, but these two programs are not connected to all the other programs that you ran before.

Now in yet another shell run:

% dtk-connectRemoteSharedMem hello localhost:2345  

Now you should be able to type in any of the dtk-server program windows and see all the running dtk-readStrings programs reading the same text.

Now Ctrl-c one of the dtk-server programs.  The other set of "hello" readers and writer run as before they connected.

Can you connect the two sets of "hello" again?

Cleaning Up DTK Shared Memory

% ls -l $DTK_SHAREDMEM_DIR
total 8
-rw-rw-rw-    1 lanceman lanceman     6624 May 14 14:25 hello

% dtk-destroySharedMem hello  
% ls -l $DTK_SHAREDMEM_DIR  
ls: /tmp/dtkSharedMem: No such file or directory

Reminder: run dtk-destroySharedMem --help

The dtk-destroySharedMem program is used to remove all system resources associated with a DTK shared memory file.  On GNU/Linux systems this includes a system V semaphore array and the DTK shared memory file.  The DTK shared memory file keeps in it the information about the system V semaphore array.  So if you delete this file you will not have a record as to what system V semaphore array to remove.  On IRIX systems pthreads read/write locks are used in place of the system V semaphore array, so deleting the DTK shared memory file will work fine, but we recommend using the dtk-destroySharedMem program to keep your codes portable.  If you call dtk-destroySharedMem on DTK shared memory files that are being used, the programs using them will get unhappy.

Now kill all the other programs and run:

% ls -l /tmp/dtkSharedMem   
total 8
-rw-rw-rw-    1 lanceman lanceman     1208 May 14 14:18 foo
-rw-rw-rw-    1 lanceman lanceman     6776 May 14 14:26 hello
% dtk-destroySharedMem --recursive  
% ls -l /tmp/dtkSharedMem   
ls: /tmp/dtkSharedMem: No such file or directory

Keep in mind that most of the programs (except dtk-server and dtk-floatScope) have little source code.  Most of the code for these programs is in the DTK API, so tweaking a DTK program is not a big task.

Another good thing to know about is the system V IPC resources, though in some installations DTK can be configured to use other semaphore methods.  DTK shared memory can use system V semaphore arrays, which can be listed with ipcs, and removed with ipcrm.  It may be handy to note that DTK shared memory always uses system V semaphore arrays with 3 semaphores, so if there is a system V semaphore array that is not 3 in size (nsems!=3) then it is not from DTK shared memory.