1/*
2 *  Copyright (c) 2011 The WebRTC project authors. All Rights Reserved.
3 *
4 *  Use of this source code is governed by a BSD-style license
5 *  that can be found in the LICENSE file in the root of the source
6 *  tree. An additional intellectual property rights grant can be found
7 *  in the file PATENTS.  All contributing project authors may
8 *  be found in the AUTHORS file in the root of the source tree.
9 */
10
11/*
12 * This singleton can be used for logging data for offline processing. Data
13 * logged with it can conveniently be parsed and processed with e.g. Matlab.
14 *
15 * Following is an example of the log file format, starting with the header
16 * row at line 1, and the data rows following.
17 * col1,col2,col3,multi-value-col4[3],,,col5
18 * 123,10.2,-243,1,2,3,100
19 * 241,12.3,233,1,2,3,200
20 * 13,16.4,-13,1,2,3,300
21 *
22 * As can be seen in the example, a multi-value-column is specified with the
23 * name followed the number of elements it contains. This followed by
24 * number of elements - 1 empty columns.
25 *
26 * Without multi-value-columns this format can be natively by Matlab. With
27 * multi-value-columns a small Matlab script is needed, available at
28 * trunk/tools/matlab/parseLog.m.
29 *
30 * Table names and column names are case sensitive.
31 */
32
33#ifndef WEBRTC_SYSTEM_WRAPPERS_INTERFACE_DATA_LOG_H_
34#define WEBRTC_SYSTEM_WRAPPERS_INTERFACE_DATA_LOG_H_
35
36#include <string>
37
38#include "data_log_impl.h"
39
40namespace webrtc {
41
42class DataLog {
43 public:
44  // Creates a log which uses a separate thread (referred to as the file
45  // writer thread) for writing log rows to file.
46  //
47  // Calls to this function after the log object has been created will only
48  // increment the reference counter.
49  static int CreateLog();
50
51  // Decrements the reference counter and deletes the log when the counter
52  // reaches 0. Should be called equal number of times as successful calls to
53  // CreateLog or memory leak will occur.
54  static void ReturnLog();
55
56  // Combines the string table_name and the integer table_id into a new string
57  // table_name + _ + table_id. The new string will be lower-case.
58  static std::string Combine(const std::string& table_name, int table_id);
59
60  // Adds a new table, with the name table_name, and creates the file, with the
61  // name table_name + ".txt", to which the table will be written.
62  // table_name is treated in a case sensitive way.
63  static int AddTable(const std::string& table_name);
64
65  // Adds a new column to a table. The column will be a multi-value-column
66  // if multi_value_length is greater than 1.
67  // table_name and column_name are treated in a case sensitive way.
68  static int AddColumn(const std::string& table_name,
69                       const std::string& column_name,
70                       int multi_value_length);
71
72  // Inserts a single value into a table with name table_name at the column with
73  // name column_name.
74  // Note that the ValueContainer makes use of the copy constructor,
75  // operator= and operator<< of the type T, and that the template type must
76  // implement a deep copy copy constructor and operator=.
77  // Copy constructor and operator= must not be disabled for the type T.
78  // table_name and column_name are treated in a case sensitive way.
79  template<class T>
80  static int InsertCell(const std::string& table_name,
81                        const std::string& column_name,
82                        T value) {
83    DataLogImpl* data_log = DataLogImpl::StaticInstance();
84    if (data_log == NULL)
85      return -1;
86    return data_log->InsertCell(
87             table_name,
88             column_name,
89             new ValueContainer<T>(value));
90  }
91
92  // Inserts an array of values into a table with name table_name at the
93  // column specified by column_name, which must be a multi-value-column.
94  // Note that the MultiValueContainer makes use of the copy constructor,
95  // operator= and operator<< of the type T, and that the template type
96  // must implement a deep copy copy constructor and operator=.
97  // Copy constructor and operator= must not be disabled for the type T.
98  // table_name and column_name are treated in a case sensitive way.
99  template<class T>
100  static int InsertCell(const std::string& table_name,
101                        const std::string& column_name,
102                        const T* array,
103                        int length) {
104    DataLogImpl* data_log = DataLogImpl::StaticInstance();
105    if (data_log == NULL)
106      return -1;
107    return data_log->InsertCell(
108             table_name,
109             column_name,
110             new MultiValueContainer<T>(array, length));
111  }
112
113  // For the table with name table_name: Writes the current row to file.
114  // Starts a new empty row.
115  // table_name is treated in a case-sensitive way.
116  static int NextRow(const std::string& table_name);
117};
118
119}  // namespace webrtc
120
121#endif  // WEBRTC_SYSTEM_WRAPPERS_INTERFACE_DATA_LOG_H_
122