Library Quick Start

Library Quick Start

Structures and Fields

TSDB implements a runtime structure system, as opposed to C's compile-time defined structures. You need to do this so that TSDB utilities can support any record structure without needing to be recompiled. The dynamic structure system is relatively simple to use and should not contribute much overhead.

The first class to understand is the Structure class. This represents a defined data structure as a collections of Fields. In C, you would define a structure as something like this:

struct stock_trades{
  long long timestamp,
  double price,
  int quantity
}

In TSDB, you would define the same struct in this way:

std::vector<Field*> fields;
fields.push_back(new tsdb::TimestampField("timestamp"));
fields.push_back(new tsdb::DoubleField("price"));
fields.push_back(new tsdb::Int32Field("quantity"));

tsdb::Structure stock_trades(fields,true);

The Structure class holds the definition of a struct, but you don't create an instance of Structure to hold some actual data. In C, you might do something like this to allocate some memory to hold a stock trade: struct stock_trade *foo; foo = malloc(sizeof(stock_trade));. In TSDB, you would instead declare a pointer of type void and use a similar malloc command.

void *foo;
foo = malloc(stock_trade.getSizeOf());

Sidenote: I know this is a terrible way of handling memory. There is no way to allocate a stock_trade on the stack in TSDB, and void pointers are passed around excessively. That is to be fixed in the future.

Now, to set a member of the structure in C, you would just do foo->timestamp = 0; foo->price = 1.234; foo->quantity = 5. In TSDB, this is a little more complicated. Because you don't have the advantage of compile-time casting of numbers to the appropriate type, you need to get creative. TSDB has utilities to parse strings into the appropriate data type (say, for when you want to read a CSV file). That will be covered later. For now, we are going to cheat and use the compiler:

long long footimestamp = 0;
double fooprice = 1.234;
int fooquantity = 5;

stock_price.setMember(foo,0,&footimestamp);
stock_price.setMember(foo,1,&fooprice);
stock_price.setMember(foo,2,&fooquantity);

Here, we call the setMember() method, which takes a pointer to a memory block of the appropriate size of the Structure. Then second argument is which member we want to set (starting from 0). The final is a pointer to the memory block that will be copied into the appropriate spot in the Structure.

To read a member of a Structure, you do something similar. Whereas in C you can simply do printf("The price was: %f\n", foo->price);, you need to do something slightly more complex in TSDB:

printf("The price was: %f\n", *((double) stock_trade.pointerToMember(foo,1)));

Here, pointerToMember() returns a pointer to the second member of foo, using the Structure class stock_trade to get the correct offset. This is a void pointer, so it needs to be cast to a double before dereferencing when passing it to printf.

Tables

Timeseries