1 // Copyright (c) 2011 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 // 5 // A StatsTable is a table of statistics. It can be used across multiple 6 // processes and threads, maintaining cheap statistics counters without 7 // locking. 8 // 9 // The goal is to make it very cheap and easy for developers to add 10 // counters to code, without having to build one-off utilities or mechanisms 11 // to track the counters, and also to allow a single "view" to display 12 // the contents of all counters. 13 // 14 // To achieve this, StatsTable creates a shared memory segment to store 15 // the data for the counters. Upon creation, it has a specific size 16 // which governs the maximum number of counters and concurrent 17 // threads/processes which can use it. 18 // 19 20 #ifndef BASE_METRICS_STATS_TABLE_H_ 21 #define BASE_METRICS_STATS_TABLE_H_ 22 23 #include <string> 24 25 #include "base/base_export.h" 26 #include "base/basictypes.h" 27 #include "base/containers/hash_tables.h" 28 #include "base/memory/shared_memory.h" 29 #include "base/synchronization/lock.h" 30 #include "base/threading/thread_local_storage.h" 31 #include "build/build_config.h" 32 33 #if defined(OS_POSIX) 34 #include "base/file_descriptor_posix.h" 35 #endif 36 37 namespace base { 38 39 class BASE_EXPORT StatsTable { 40 public: 41 // Identifies a StatsTable. We often want to share these between processes. 42 // 43 // On Windows, we use a named shared memory segment so the table identifier 44 // should be a relatively unique string identifying the table to use. An 45 // empty string can be used to use an anonymous shared memory segment for 46 // cases where the table does not need to be shared between processes. 47 // 48 // Posix does not support named memory so we explicitly share file 49 // descriptors. On Posix, pass a default-constructed file descriptor if a 50 // handle doesn't already exist, and a new one will be created. 51 // 52 // If a table doesn't already exist with the given identifier, a new one will 53 // be created with zeroed counters. 54 #if defined(OS_POSIX) 55 typedef FileDescriptor TableIdentifier; 56 #elif defined(OS_WIN) 57 typedef std::string TableIdentifier; 58 #endif 59 60 // Create a new StatsTable. 61 // 62 // max_threads is the maximum number of threads the table will support. 63 // If the StatsTable already exists, this number is ignored. 64 // 65 // max_counters is the maximum number of counters the table will support. 66 // If the StatsTable already exists, this number is ignored. 67 StatsTable(const TableIdentifier& table, 68 int max_threads, 69 int max_counters); 70 71 // Destroys the StatsTable. When the last StatsTable is destroyed 72 // (across all processes), the StatsTable is removed from disk. 73 ~StatsTable(); 74 75 // For convenience, we create a static table. This is generally 76 // used automatically by the counters. 77 static StatsTable* current(); 78 79 // Set the global table for use in this process. 80 static void set_current(StatsTable* value); 81 82 // Get the slot id for the calling thread. Returns 0 if no 83 // slot is assigned. 84 int GetSlot() const; 85 86 // All threads that contribute data to the table must register with the 87 // table first. This function will set thread local storage for the 88 // thread containing the location in the table where this thread will 89 // write its counter data. 90 // 91 // name is just a debugging tag to label the thread, and it does not 92 // need to be unique. It will be truncated to kMaxThreadNameLength-1 93 // characters. 94 // 95 // On success, returns the slot id for this thread. On failure, 96 // returns 0. 97 int RegisterThread(const std::string& name); 98 99 // Returns the number of threads currently registered. This is really not 100 // useful except for diagnostics and debugging. 101 int CountThreadsRegistered() const; 102 103 // Find a counter in the StatsTable. 104 // 105 // Returns an id for the counter which can be used to call GetLocation(). 106 // If the counter does not exist, attempts to create a row for the new 107 // counter. If there is no space in the table for the new counter, 108 // returns 0. 109 int FindCounter(const std::string& name); 110 111 // TODO(mbelshe): implement RemoveCounter. 112 113 // Gets the location of a particular value in the table based on 114 // the counter id and slot id. 115 int* GetLocation(int counter_id, int slot_id) const; 116 117 // Gets the counter name at a particular row. If the row is empty, 118 // returns NULL. 119 const char* GetRowName(int index) const; 120 121 // Gets the sum of the values for a particular row. 122 int GetRowValue(int index) const; 123 124 // Gets the sum of the values for a particular row for a given pid. 125 int GetRowValue(int index, int pid) const; 126 127 // Gets the sum of the values for a particular counter. If the counter 128 // does not exist, creates the counter. 129 int GetCounterValue(const std::string& name); 130 131 // Gets the sum of the values for a particular counter for a given pid. 132 // If the counter does not exist, creates the counter. 133 int GetCounterValue(const std::string& name, int pid); 134 135 // The maxinum number of counters/rows in the table. 136 int GetMaxCounters() const; 137 138 // The maxinum number of threads/columns in the table. 139 int GetMaxThreads() const; 140 141 #if defined(OS_POSIX) 142 // Get the underlying shared memory handle for the table. 143 base::SharedMemoryHandle GetSharedMemoryHandle() const; 144 #endif 145 146 // The maximum length (in characters) of a Thread's name including 147 // null terminator, as stored in the shared memory. 148 static const int kMaxThreadNameLength = 32; 149 150 // The maximum length (in characters) of a Counter's name including 151 // null terminator, as stored in the shared memory. 152 static const int kMaxCounterNameLength = 64; 153 154 // Convenience function to lookup a counter location for a 155 // counter by name for the calling thread. Will register 156 // the thread if it is not already registered. 157 static int* FindLocation(const char *name); 158 159 private: 160 class Internal; 161 struct TLSData; 162 typedef hash_map<std::string, int> CountersMap; 163 164 // Returns the space occupied by a thread in the table. Generally used 165 // if a thread terminates but the process continues. This function 166 // does not zero out the thread's counters. 167 // Cannot be used inside a posix tls destructor. 168 void UnregisterThread(); 169 170 // This variant expects the tls data to be passed in, so it is safe to 171 // call from inside a posix tls destructor (see doc for pthread_key_create). 172 void UnregisterThread(TLSData* tls_data); 173 174 // The SlotReturnFunction is called at thread exit for each thread 175 // which used the StatsTable. 176 static void SlotReturnFunction(void* data); 177 178 // Locates a free slot in the table. Returns a number > 0 on success, 179 // or 0 on failure. The caller must hold the shared_memory lock when 180 // calling this function. 181 int FindEmptyThread() const; 182 183 // Locates a counter in the table or finds an empty row. Returns a 184 // number > 0 on success, or 0 on failure. The caller must hold the 185 // shared_memory_lock when calling this function. 186 int FindCounterOrEmptyRow(const std::string& name) const; 187 188 // Internal function to add a counter to the StatsTable. Assumes that 189 // the counter does not already exist in the table. 190 // 191 // name is a unique identifier for this counter, and will be truncated 192 // to kMaxCounterNameLength-1 characters. 193 // 194 // On success, returns the counter_id for the newly added counter. 195 // On failure, returns 0. 196 int AddCounter(const std::string& name); 197 198 // Get the TLS data for the calling thread. Returns NULL if none is 199 // initialized. 200 TLSData* GetTLSData() const; 201 202 Internal* internal_; 203 204 // The counters_lock_ protects the counters_ hash table. 205 base::Lock counters_lock_; 206 207 // The counters_ hash map is an in-memory hash of the counters. 208 // It is used for quick lookup of counters, but is cannot be used 209 // as a substitute for what is in the shared memory. Even though 210 // we don't have a counter in our hash table, another process may 211 // have created it. 212 CountersMap counters_; 213 ThreadLocalStorage::Slot tls_index_; 214 215 DISALLOW_COPY_AND_ASSIGN(StatsTable); 216 }; 217 218 } // namespace base 219 220 #endif // BASE_METRICS_STATS_TABLE_H_ 221
