Installation Guide: Data Driver
Convention
-
Names in this color:
specific names. You must use them as they are.
-
Names in this color:
example names. You can change them as you want.
Files
-
LRDataProvider.h: C/C++ header file of
linear road data driver
-
libLRDataProvider.a: library
of linear road data driver
-
DataFeeder.cpp: C/C++ example that implements the benchmark using the Data Driver
-
datafile20seconds.dat: Example input data file, which contains data of 20 seconds.
-
datafile3hours.dat: Example input data file, which contains data of 3 hours.
User guide
LRDataProvider is a data driver written in C/C++ and compiled/run in gcc version 3.3.1 - Mandrake Linux 9.2 3.3.3-2mdk. This data driver takes the flat file generated by "Data
Generator" and delivers the data to Linear Road application in a manner
consistent with their timestamps. LRDataProvider reads the input file and puts
data in its own buffer. Whenever the implementation called "GetData", the
driver will return only data that satisfy the timestamp condition.
This driver inlcudes the header file pthread.h. So make sure you
already have pthread library. You can check it by:
. Looking for pthread.h in
/usr/include/ or your "include" folder
. Looking for libpthread*
in /usr/lib/
or your "lib" folder
In order to use this driver you have to do the following
-
Download DataDriver
from the Linear Road website
-
Extract DataDriver into a folder such as
/home/username/datadiver/
-
Copy two files /home/username/datadiver/LRDataProvider.h
and /home/username/datadiver/ libLRDataProvider.a
to your working directory.
-
Include LRDataProvider.h in your file named
yourCfile.cpp
-
In yourCfile.cpp
, do the following steps in the exact orders:
-
Declare and initialize a pthread_mutex_t vairable.
This variable is used to control the serializing shared resources.
pthread_mutex_t mutex_lock = PTHREAD_MUTEX_INITIALIZER;
-
Declare and new a CLRDataProvider called
provider
CLRDataProvider* provider = new CLRDataProvider();
-
Initialize the provider. This function is mainly
used to allocate memory for the buffer of the data driver and open the data file.
int ret = provider->Initialize(dataFileName, bufferSize, &mutex_lock);
or
int ret = provider->Initialize(dataFileName, &mutex_lock)
-
char* dataFileName: Name of input
data file generated by Data Generator
-
int bufferSize: Bufer size of the
provider. This is the maximun number of tuples in the buffer. Defaut value is
10000, which is enough for data of 30 seconds. If you want to use the default
value, you don't have to provide this parameter. Note that this is the buffer
of the data driver, which is different from the return buffer of
GetData, whose data will be used by the implementation. When GetData is
called, the driver will return only data in the buffer that satisfy the
timestamp condition.
-
pthread_mutex_t mutex_lock: Above
declared variable
If the return value of Initialize is different from SUCCESS
(a constant defined in LRDataProvider.h), an error
has happened. You should stop here and check return error code. The constant
codes are defined in LRDataProvider.h as follows:
-
SUCCESS
-
END_OF_FILE: End of data file
-
ERROR_FILE_NOT_FOUND: Data file not found. Check data file path name.
-
ERROR_INVALID_FILE: Invalid file handler. Restart the system.
-
ERROR_BUFFER_OVERFLOW: Buffer over flow. Increase the buffer size when calling
Initialize function.
The driver takes care of its buffer allocation and deallocation. You don't have
to worry about that.
-
Call PrepareData to start running the driver. This
function will start the clock.
int ret = provider->PrepareData(provider)
Like Initialize function, you should check the error code if the return value
is different from SUCCESS.
-
Declare and allocate your buffer, which is the number of tuples you want to get. This
buffer should be big enough to contain data that satisfy the timestamp condition. Otherwise, you can get that data several times.
LPTuple lpTuples = new Tuple[nMaxTuples];
-
LPTuple: Pointer of tuple defined in
LRDataProvider.h
-
int nMaxTuples: your buffer size
Note that you are responsible for allocating and deallocating this buffer.
-
Repeat to call GetData whenever you need. This function will return only data
that satisfy the timestamp condition.
int ret = provider->GetData(lpTuples, nMaxTuples, nTuplesRead);
-
LPTuple lpTuples: Your buffer, which is
allocated above. Data will be returned in this buffer.
-
int nMaxTuples: your buffer size
or number of tuples you want to read. This should be the size of lpTuples.
-
int nTuplesRead: number of return
tuples. This value will be always less than or equal to nMaxTuples.
You should check the return value (ret) of this function. The return code is
exactly the same as defined in step 3. When the return code is END_OF_FILE, you
should stop calling GetData. Otherwise, you will always get zero return tuple.
Now you have data. You are free to do anything to you want to get data from the
buffer to your implementation. But remember, the clock is ticking from the
driver, so use them efficiently.
If you use the default buffer size (10000 tuples), it will be working well for
data of 30 seconds. You should increase that value if you want more time
between every GetData times. This is simple done by passing parameter in the
Initialize function.
-
Uninitiaize the provider. This function will close
data file and deallocate the driver's buffer. Don't forget to call this
function when you don't want to get data anymore.
provider->Uninitialize();
Tuple is a stucture of a line read from the data file. It is defined in
LRDataProvider.h. You can asscess all its member directly.
All functions and other variables are also defined in LRDataProvider.h.
You are free to access them if they are declared public
-
Compile yourCfile.cpp to yourCfile.o
object file
g++ -c yourCfile.cpp
or
gcc -c yourCfile.cpp
-
Link yourCfile.o to YourExecutedFileName
by using:
g++ -o YourExecutedFileName yourCfile.o -lpthread libLRDataProvider.a
Make sure libLRDataProvider.a is always behind
-lpthread and other libaries
-
Run YourExecutedFileName by typing:
./YourExecutedFileName yourParameters
Click here for a complete
example (DataFeeder.cpp)