| // Copyright (c) 2011 The Chromium Authors. All rights reserved. | |
| // Use of this source code is governed by a BSD-style license that can be | |
| // found in the LICENSE file. | |
| // | |
| // A StatsTable is a table of statistics. It can be used across multiple | |
| // processes and threads, maintaining cheap statistics counters without | |
| // locking. | |
| // | |
| // The goal is to make it very cheap and easy for developers to add | |
| // counters to code, without having to build one-off utilities or mechanisms | |
| // to track the counters, and also to allow a single "view" to display | |
| // the contents of all counters. | |
| // | |
| // To achieve this, StatsTable creates a shared memory segment to store | |
| // the data for the counters. Upon creation, it has a specific size | |
| // which governs the maximum number of counters and concurrent | |
| // threads/processes which can use it. | |
| // | |
| #ifndef BASE_METRICS_STATS_TABLE_H_ | |
| #define BASE_METRICS_STATS_TABLE_H_ | |
| #include <string> | |
| #include "base/base_export.h" | |
| #include "base/basictypes.h" | |
| #include "base/hash_tables.h" | |
| #include "base/synchronization/lock.h" | |
| #include "base/threading/thread_local_storage.h" | |
| namespace base { | |
| class BASE_EXPORT StatsTable { | |
| public: | |
| // Create a new StatsTable. | |
| // If a StatsTable already exists with the specified name, this StatsTable | |
| // will use the same shared memory segment as the original. Otherwise, | |
| // a new StatsTable is created and all counters are zeroed. | |
| // | |
| // name is the name of the StatsTable to use. | |
| // | |
| // max_threads is the maximum number of threads the table will support. | |
| // If the StatsTable already exists, this number is ignored. | |
| // | |
| // max_counters is the maximum number of counters the table will support. | |
| // If the StatsTable already exists, this number is ignored. | |
| StatsTable(const std::string& name, int max_threads, int max_counters); | |
| // Destroys the StatsTable. When the last StatsTable is destroyed | |
| // (across all processes), the StatsTable is removed from disk. | |
| ~StatsTable(); | |
| // For convenience, we create a static table. This is generally | |
| // used automatically by the counters. | |
| static StatsTable* current() { return global_table_; } | |
| // Set the global table for use in this process. | |
| static void set_current(StatsTable* value) { global_table_ = value; } | |
| // Get the slot id for the calling thread. Returns 0 if no | |
| // slot is assigned. | |
| int GetSlot() const; | |
| // All threads that contribute data to the table must register with the | |
| // table first. This function will set thread local storage for the | |
| // thread containing the location in the table where this thread will | |
| // write its counter data. | |
| // | |
| // name is just a debugging tag to label the thread, and it does not | |
| // need to be unique. It will be truncated to kMaxThreadNameLength-1 | |
| // characters. | |
| // | |
| // On success, returns the slot id for this thread. On failure, | |
| // returns 0. | |
| int RegisterThread(const std::string& name); | |
| // Returns the number of threads currently registered. This is really not | |
| // useful except for diagnostics and debugging. | |
| int CountThreadsRegistered() const; | |
| // Find a counter in the StatsTable. | |
| // | |
| // Returns an id for the counter which can be used to call GetLocation(). | |
| // If the counter does not exist, attempts to create a row for the new | |
| // counter. If there is no space in the table for the new counter, | |
| // returns 0. | |
| int FindCounter(const std::string& name); | |
| // TODO(mbelshe): implement RemoveCounter. | |
| // Gets the location of a particular value in the table based on | |
| // the counter id and slot id. | |
| int* GetLocation(int counter_id, int slot_id) const; | |
| // Gets the counter name at a particular row. If the row is empty, | |
| // returns NULL. | |
| const char* GetRowName(int index) const; | |
| // Gets the sum of the values for a particular row. | |
| int GetRowValue(int index) const; | |
| // Gets the sum of the values for a particular row for a given pid. | |
| int GetRowValue(int index, int pid) const; | |
| // Gets the sum of the values for a particular counter. If the counter | |
| // does not exist, creates the counter. | |
| int GetCounterValue(const std::string& name); | |
| // Gets the sum of the values for a particular counter for a given pid. | |
| // If the counter does not exist, creates the counter. | |
| int GetCounterValue(const std::string& name, int pid); | |
| // The maxinum number of counters/rows in the table. | |
| int GetMaxCounters() const; | |
| // The maxinum number of threads/columns in the table. | |
| int GetMaxThreads() const; | |
| // The maximum length (in characters) of a Thread's name including | |
| // null terminator, as stored in the shared memory. | |
| static const int kMaxThreadNameLength = 32; | |
| // The maximum length (in characters) of a Counter's name including | |
| // null terminator, as stored in the shared memory. | |
| static const int kMaxCounterNameLength = 64; | |
| // Convenience function to lookup a counter location for a | |
| // counter by name for the calling thread. Will register | |
| // the thread if it is not already registered. | |
| static int* FindLocation(const char *name); | |
| private: | |
| class Private; | |
| struct TLSData; | |
| typedef hash_map<std::string, int> CountersMap; | |
| // Returns the space occupied by a thread in the table. Generally used | |
| // if a thread terminates but the process continues. This function | |
| // does not zero out the thread's counters. | |
| // Cannot be used inside a posix tls destructor. | |
| void UnregisterThread(); | |
| // This variant expects the tls data to be passed in, so it is safe to | |
| // call from inside a posix tls destructor (see doc for pthread_key_create). | |
| void UnregisterThread(TLSData* tls_data); | |
| // The SlotReturnFunction is called at thread exit for each thread | |
| // which used the StatsTable. | |
| static void SlotReturnFunction(void* data); | |
| // Locates a free slot in the table. Returns a number > 0 on success, | |
| // or 0 on failure. The caller must hold the shared_memory lock when | |
| // calling this function. | |
| int FindEmptyThread() const; | |
| // Locates a counter in the table or finds an empty row. Returns a | |
| // number > 0 on success, or 0 on failure. The caller must hold the | |
| // shared_memory_lock when calling this function. | |
| int FindCounterOrEmptyRow(const std::string& name) const; | |
| // Internal function to add a counter to the StatsTable. Assumes that | |
| // the counter does not already exist in the table. | |
| // | |
| // name is a unique identifier for this counter, and will be truncated | |
| // to kMaxCounterNameLength-1 characters. | |
| // | |
| // On success, returns the counter_id for the newly added counter. | |
| // On failure, returns 0. | |
| int AddCounter(const std::string& name); | |
| // Get the TLS data for the calling thread. Returns NULL if none is | |
| // initialized. | |
| TLSData* GetTLSData() const; | |
| Private* impl_; | |
| // The counters_lock_ protects the counters_ hash table. | |
| base::Lock counters_lock_; | |
| // The counters_ hash map is an in-memory hash of the counters. | |
| // It is used for quick lookup of counters, but is cannot be used | |
| // as a substitute for what is in the shared memory. Even though | |
| // we don't have a counter in our hash table, another process may | |
| // have created it. | |
| CountersMap counters_; | |
| ThreadLocalStorage::Slot tls_index_; | |
| static StatsTable* global_table_; | |
| DISALLOW_COPY_AND_ASSIGN(StatsTable); | |
| }; | |
| } // namespace base | |
| #endif // BASE_METRICS_STATS_TABLE_H_ |