Installation Guide: Data Driver

Convention

Files

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

  1. Download DataDriver from the Linear Road website
  2. Extract DataDriver into a folder such as /home/username/datadiver/
  3. Copy two files /home/username/datadiver/LRDataProvider.h and /home/username/datadiver/ libLRDataProvider.a to your working directory.
  4. Include LRDataProvider.h in your file named yourCfile.cpp
  5. In yourCfile.cpp , do the following steps in the exact orders:
    1. 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;
    2. Declare and new a CLRDataProvider called provider
      CLRDataProvider* provider = new CLRDataProvider();
    3. 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.
    4. 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.
    5. 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.
    6. 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.
    7. 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

  6. Compile yourCfile.cpp to yourCfile.o object file
    g++ -c yourCfile.cpp
    or
    gcc -c yourCfile.cpp
  7. 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
  8. Run YourExecutedFileName by typing:
    ./YourExecutedFileName yourParameters
  • Click here for a complete example (DataFeeder.cpp)