Run Time Access |
What is RTA?
RTA is a memory resident database and virtual file
system interface. It is not a stand-alone database server or
file system but a library which offers
up the program's internal structures and arrays as database tables or
as files in a file system. The database interface uses a subset of the
Postgres protocol and is compatible with the Postgres bindings for "C",
PHP, and the Postgres command line tool, psql.
What is the purpose of RTA?
It provides a means for external programs to view and edit the
tables in your running program. This makes debugging easier and
means that the user interface parts of your system can be kept
apart from the core functionality.
So, is this a database, or what?
No, it is *not* a database. It is an API which lets external
programs view and edit your internal data as if the data were in a
database or as files in a file system.
Is this like the /proc filesystem?
Yes, in a way. The /proc system lets you view the kernel's internal
data as if the data were stored in files in a filesystem. RTA has
two libraries, one lets you view your program's internal tables
(arrays of structures) as if they were files in a file system, and
the other lets you view your arrays of structures as if they were
tables in a PostgreSQL database.
Why PostgreSQL?
Mostly because both the design and the documentation of the
PostgreSQL protocol are very clean. PostgreSQL offers a simple,
well documented protocol to the client. (Our thanks to the designers
and tech-writers for PostgreSQL.)
What SQL commands are implemented?
Only two: SELECT and UPDATE, and even then it is only a subset of
the usual SELECT and UPDATE. See rta.h for the syntax details of
the commands. RTA does not implement transactions.
What SQL/Postgres commands are not
implemented?
This is not a database. We do not implement INSERT or DELETE since
tables are (for the most part) fixed in size. Nor do we have CREATE
TABLE, ALTER TABLE, or DROP TABLE.
The command line tool for PostgreSQL, psql, will connect to a program
with RTA, but none of the psql backslash commands will work (since
most of the backslash commands require a real PostgreSQL database).
Why such a small subset of SQL?
This is not a database; it is an API. SELECT and UPDATE are the
minimum needed to read and edit the data in your running program.
What file system commands are in RTA?
The read(), write(), and readdir() commands are implemented as is
the stat() function. Minimal stubs are provided for both open()
and truncate().
Who should not use RTA?
RTA is great if you have data already arranged as structs or as
array of structs. It is a little more difficult to use if you have
lots of structs pointing to other structs pointing to other
structs. That is, it is a good fit for simple tables of data and is
not a good fit for a deeply nested tree structure of data.
It is also best for single process applications where the data is
in one memory space. For instance, it might not be a good fit for
Apache which forks several equal, independent processes.
How big is it?
The stripped shared-object SQL interface library (librtadb.so.2)
is 55 KB and the static (.a) library is 46 KB. The stripped virtual
file system interface
(librtafs.so.2) is 28KB and the static library is 11KB. Note that
to use the virtual file system interface you need to load the SQL
interface as well.
Do I need to know SQL to use RTA?
Not really. There are only two commands and they match pretty
well with the intuitive idea of "change this column in this table
where ...". It is pretty simple.
Also, the librtafs library lets you avoid SQL entirely if you wish.
How difficult is it to learn and use RTA?
It is easy to learn. There are only two important data structures
(one to describe a table and one to describe a column) and only seven
subroutines in the API. The tutorial elsewhere on this page should
give you a pretty good idea of the simplicity of the approach.
It is simple but *may* require some effort on your part. Each table
and each column in each table needs to be defined in a data
structure. While simple, it can be a fair amount of work.
How do I report bugs?
Please select "Contact Info" from the menu above to open a
query form. Please give as much detail as possible.
Where can I get help?
Please select "Contact Info" from the menu above to open a
query form. Please give as much detail as possible.
Can I send you money?
Please send bug reports and change requests. Send money to the Free
Software Foundation.
What do I need to do to use RTA in my
program?
You need to describe each table you wish to make available. A table
is an array of structures. Each member of the structure forms a
column of the table. The table description includes attributes of
the table in general and a description of each column in the table.
See the sample application and the API reference for more
detail.
What libraries, tools and include files are
needed?
We use the following system include files: libgen.h, limits.h,
stdarg.h, stddef.h, stdio.h, stdlib.h, string.h, syslog.h, and the
following system and utility calls: closelog(), dirname(),
fclose(), fdopen(), fgets(), fopen(), fprintf(), free(), malloc(),
memchr(), mkstemp(), offsetof(), openlog(), rename(), snprintf(),
sprintf(), sscanf(), strcat(), strcmp(), strcpy(), strlen(),
strncmp(), strncpy(), strstr(), syslog(), va_arg(), va_end(),
va_start(). You will need yacc and lex to build RTA.
The virtual file system interface to RTA (librtafs) is built on
top of librtadb and the "FUSE" package by Miklos Szeredi
Do I need the Postgres libraries?
Your application does not need any libraries or include files from
the PostgreSQL distribution. Your *client* applications may need
PostgreSQL libraries as appropriate.
Can I link to it statically?
Yes, You can link to the .a file or just include the .c files in
the build of your application.
What has it been tested on?
It has been used successfully Red Hat 8.0 and 9.0,
and on Mandrake 9.1 and 9.2 systems.
Can I add my own data type?
Yes. You will need to modify the lex program to recognize the new
data type as well as the .c files which print or compare its
values.
Why are there "magic" numbers in the
code?
Several places in the code contain what seem like magic values.
These are all related to the PostgreSQL protocol and should all be
described by comments in the surrounding code.
Why are the pseudo-tables arrays of
pointers?
The short answer is to save memory. If rta_add_table() were to copy
the table definition your application would have the definition two
places in memory: internal to RTA, and in your application code. By
saving the pointers to the table and column definitions we avoid
using lots of memory to duplicate data. Saving pointers has the
second advantage of letting you change the table definition on the
fly if needed.
Why do I get segmentation
violations?
We've tried very hard to eliminate memory leaks and segmentation
violations from the RTA package but some might have slipped
through. A common source of problems is overrunning a string. Be
sure to verify that your strings have the proper size specified in
the column definitions.
How can I change the size of a
table?
Allocate enough memory to store the new, larger table. Copy the old
table into the new space. Initialize the new rows added. Copy the
address of the new table into the "address" field of the table
definition and update the "nrows" field with the new number of
rows.
Why use native data type instead of INT4
and INT8?
The idea is to give easy access to *your* data structures. Since
most programmers use the native int, long long, and float, we do
too.
Why do I get "error while loading shared libraries:
librtadb.so.2"?
You need to put the librtadb.so and librtafs.so files into one of
the system library directories or you need to something like "export
LD_LIBRARY_PATH=../src" in order to let the application find the
library.
How big should I make the output buffer for
dbcommand()?
It depends on the number of rows and the size and number of fields
you request. You should be able to estimate the number of
characters in your response. Assume that strings are returned with
all bytes filled, that integers return 12 characters per field,
longs return 24, and floats return 24. Thus if you request two
integers, a 40 byte string and a float, you would need about
40+(2*12)+24=88 bytes. The Postgres overhead per row returned is
about 4 bytes. Make the output buffer for dbcommand() big enough to
hold the maximum number of rows you want times the size of each
row. Be sure to use LIMIT and OFFSET to step through a big list of
returned rows.
Why must a write() have all data in a single
buffer?
There are two reasons. First, RTA requires a single write buffer
in order to be sure that all table writes are atomic. Without
atomic table writes we could not guarantee table consistency.
Second, the FUSE package, upon which the file system interface is
based, does not implement or use file descriptors. The write call
has as input a path, buffer, count, and offset. This leaves open
the possibility that two programs writing to the same row or column
could conflict and leave the table an inconsistent state.
Can I export a simple variable?
Sure. Just define a single column for your variable and a table
with a single row. You can make visible simple variables, single
structures, or arrays of structures.
Which is better, the file system or the database
interface?
The database interface is better in most applications. It is
faster and it is atomic. That is, a single statement can do an
update based on the results of WHERE clause. Our use of the
file system interface has shown it to be a little fragile. You
need to be careful to not leave a mounted file system when your
program exits abnormally. This means you need some supervisory
program to unmount the file system and possibly remove and
re-install the fuse kernel module.
Is RTA thread safe?
RTA is not currently thread safe. Please contact the authors
if this is very high on your wish list.
What is in the To-Do list?
Please let the authors know what features you would like added
or removed from Run Time Access. No additional changes are
anticipated at this time, but the list of possible changes
includes: