stats_table.h revision 731df977c0511bca2206b5f333555b1205ff1f43
1// Copyright (c) 2010 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#pragma once 23 24#include <string> 25 26#include "base/basictypes.h" 27#include "base/hash_tables.h" 28#include "base/lock.h" 29#include "base/thread_local_storage.h" 30 31namespace base { 32 33class StatsTable { 34 public: 35 // Create a new StatsTable. 36 // If a StatsTable already exists with the specified name, this StatsTable 37 // will use the same shared memory segment as the original. Otherwise, 38 // a new StatsTable is created and all counters are zeroed. 39 // 40 // name is the name of the StatsTable to use. 41 // 42 // max_threads is the maximum number of threads the table will support. 43 // If the StatsTable already exists, this number is ignored. 44 // 45 // max_counters is the maximum number of counters the table will support. 46 // If the StatsTable already exists, this number is ignored. 47 StatsTable(const std::string& name, int max_threads, int max_counters); 48 49 // Destroys the StatsTable. When the last StatsTable is destroyed 50 // (across all processes), the StatsTable is removed from disk. 51 ~StatsTable(); 52 53 // For convenience, we create a static table. This is generally 54 // used automatically by the counters. 55 static StatsTable* current() { return global_table_; } 56 57 // Set the global table for use in this process. 58 static void set_current(StatsTable* value) { global_table_ = value; } 59 60 // Get the slot id for the calling thread. Returns 0 if no 61 // slot is assigned. 62 int GetSlot() const; 63 64 // All threads that contribute data to the table must register with the 65 // table first. This function will set thread local storage for the 66 // thread containing the location in the table where this thread will 67 // write its counter data. 68 // 69 // name is just a debugging tag to label the thread, and it does not 70 // need to be unique. It will be truncated to kMaxThreadNameLength-1 71 // characters. 72 // 73 // On success, returns the slot id for this thread. On failure, 74 // returns 0. 75 int RegisterThread(const std::string& name); 76 77 // Returns the number of threads currently registered. This is really not 78 // useful except for diagnostics and debugging. 79 int CountThreadsRegistered() const; 80 81 // Find a counter in the StatsTable. 82 // 83 // Returns an id for the counter which can be used to call GetLocation(). 84 // If the counter does not exist, attempts to create a row for the new 85 // counter. If there is no space in the table for the new counter, 86 // returns 0. 87 int FindCounter(const std::string& name); 88 89 // TODO(mbelshe): implement RemoveCounter. 90 91 // Gets the location of a particular value in the table based on 92 // the counter id and slot id. 93 int* GetLocation(int counter_id, int slot_id) const; 94 95 // Gets the counter name at a particular row. If the row is empty, 96 // returns NULL. 97 const char* GetRowName(int index) const; 98 99 // Gets the sum of the values for a particular row. 100 int GetRowValue(int index) const; 101 102 // Gets the sum of the values for a particular row for a given pid. 103 int GetRowValue(int index, int pid) const; 104 105 // Gets the sum of the values for a particular counter. If the counter 106 // does not exist, creates the counter. 107 int GetCounterValue(const std::string& name); 108 109 // Gets the sum of the values for a particular counter for a given pid. 110 // If the counter does not exist, creates the counter. 111 int GetCounterValue(const std::string& name, int pid); 112 113 // The maxinum number of counters/rows in the table. 114 int GetMaxCounters() const; 115 116 // The maxinum number of threads/columns in the table. 117 int GetMaxThreads() const; 118 119 // The maximum length (in characters) of a Thread's name including 120 // null terminator, as stored in the shared memory. 121 static const int kMaxThreadNameLength = 32; 122 123 // The maximum length (in characters) of a Counter's name including 124 // null terminator, as stored in the shared memory. 125 static const int kMaxCounterNameLength = 32; 126 127 // Convenience function to lookup a counter location for a 128 // counter by name for the calling thread. Will register 129 // the thread if it is not already registered. 130 static int* FindLocation(const char *name); 131 132 private: 133 class Private; 134 struct TLSData; 135 136 // Returns the space occupied by a thread in the table. Generally used 137 // if a thread terminates but the process continues. This function 138 // does not zero out the thread's counters. 139 // Cannot be used inside a posix tls destructor. 140 void UnregisterThread(); 141 142 // This variant expects the tls data to be passed in, so it is safe to 143 // call from inside a posix tls destructor (see doc for pthread_key_create). 144 void UnregisterThread(TLSData* tls_data); 145 146 // The SlotReturnFunction is called at thread exit for each thread 147 // which used the StatsTable. 148 static void SlotReturnFunction(void* data); 149 150 // Locates a free slot in the table. Returns a number > 0 on success, 151 // or 0 on failure. The caller must hold the shared_memory lock when 152 // calling this function. 153 int FindEmptyThread() const; 154 155 // Locates a counter in the table or finds an empty row. Returns a 156 // number > 0 on success, or 0 on failure. The caller must hold the 157 // shared_memory_lock when calling this function. 158 int FindCounterOrEmptyRow(const std::string& name) const; 159 160 // Internal function to add a counter to the StatsTable. Assumes that 161 // the counter does not already exist in the table. 162 // 163 // name is a unique identifier for this counter, and will be truncated 164 // to kMaxCounterNameLength-1 characters. 165 // 166 // On success, returns the counter_id for the newly added counter. 167 // On failure, returns 0. 168 int AddCounter(const std::string& name); 169 170 // Get the TLS data for the calling thread. Returns NULL if none is 171 // initialized. 172 TLSData* GetTLSData() const; 173 174 typedef hash_map<std::string, int> CountersMap; 175 176 Private* impl_; 177 178 // The counters_lock_ protects the counters_ hash table. 179 Lock counters_lock_; 180 181 // The counters_ hash map is an in-memory hash of the counters. 182 // It is used for quick lookup of counters, but is cannot be used 183 // as a substitute for what is in the shared memory. Even though 184 // we don't have a counter in our hash table, another process may 185 // have created it. 186 CountersMap counters_; 187 TLSSlot tls_index_; 188 189 static StatsTable* global_table_; 190 191 DISALLOW_COPY_AND_ASSIGN(StatsTable); 192}; 193 194} // namespace base 195 196#endif // BASE_METRICS_STATS_TABLE_H_ 197