/core/externals/update-engine/Common/KSStatsCollection.h

  1// Copyright 2008 Google Inc.
  2//
  3// Licensed under the Apache License, Version 2.0 (the "License");
  4// you may not use this file except in compliance with the License.
  5// You may obtain a copy of the License at
  6//
  7//     http://www.apache.org/licenses/LICENSE-2.0
  8//
  9// Unless required by applicable law or agreed to in writing, software
 10// distributed under the License is distributed on an "AS IS" BASIS,
 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 12// See the License for the specific language governing permissions and
 13// limitations under the License.
 14
 15#import <Foundation/Foundation.h>
 16
 17
 18// KSStatsCollection
 19//
 20// A class for managing a collection of "stats" that are persisted to disk. A
 21// "stat" is simply a key/value pair where the key is any NSString and the value
 22// is any NSNumber. Simple operations can be performed on stats, such as 
 23// incrementing and decrementing. Since stats values can be any NSNumber, both
 24// integer and floating point values are acceptable. Internally, integers are
 25// treated as "long long" types during increment and decrement operations. If
 26// you increment or decrement a stat, it is up to the you to ensure that you're
 27// not incrementing NSNumbers that are actually float values.
 28//
 29// By default, the stats collection is persisted to disk after every operation
 30// that mutates the collection. This can be disabled with the 
 31// -setAutoSynchronize: method. If you disable this, you are responsible for
 32// calling -synchronize, otherwise you may lose data if the application crashes.
 33//
 34// To be sure that your stats are correctly persisted to disk, you should make
 35// sure to call -synchronize before quitting. Do this even if auto synchronizing
 36// was enabled.
 37// 
 38// This class is thread safe.
 39//
 40// Sample usage:
 41//
 42//   KSStatsCollection *stats =
 43//     [KSStatsCollection statsCollectionWithPath:@"/tmp/test.stats"];
 44//
 45//   [stats incrementStat:@"foo"];
 46//   [stats incrementStat:@"bar"];
 47//   
 48//   NSLog(@"Recorded stats are %@", stats);
 49// 
 50@interface KSStatsCollection : NSObject {
 51 @private
 52  NSString *path_;
 53  NSMutableDictionary *stats_;
 54  BOOL autoSynchronize_;
 55}
 56
 57// Returns an autoreleased KSStatsCollection instance that will persiste the 
 58// stats to |path|.
 59+ (id)statsCollectionWithPath:(NSString *)path;
 60
 61// Returns an autoreleased KSStatsCollection instance that will persiste the 
 62// stats to |path|, and will do so automatically based on the value of
 63// |autoSync|.
 64+ (id)statsCollectionWithPath:(NSString *)path
 65              autoSynchronize:(BOOL)autoSync;
 66
 67// Returns a KSStatsCollection instance that will persist the stats to |path|.
 68// Sets autoSynchronize to YES by default.
 69- (id)initWithPath:(NSString *)path;
 70
 71// Designated initializer. Returns a KSStatsCollection instance that will
 72// persist the stats to |path|, and will do so automatically based on the value
 73// of |autoSync|.
 74- (id)initWithPath:(NSString *)path
 75   autoSynchronize:(BOOL)autoSync;
 76
 77// Returns the path where the stats are persisted.
 78- (NSString *)path;
 79
 80// Returns a copy of the internal stats dictionary.
 81- (NSDictionary *)statsDictionary;
 82
 83// Returns the number of stats in the internal dictionary.
 84- (unsigned int)count;
 85
 86// Removes all stats from this collection.
 87- (void)removeAllStats;
 88
 89// Returns YES if the stats collection will automatically write the stats to
 90// disk after every call that mutates the internal stats dictionary. The default
 91// is YES.
 92- (BOOL)autoSynchronize;
 93
 94// Sets whether stats should be automatically written to disk after mutating 
 95// methods.
 96- (void)setAutoSynchronize:(BOOL)autoSync;
 97
 98// Explicitly requests that the stats be written to disk. It is always safe to 
 99// call this method, but it is only necessary if -autoSynchronize is NO.
100- (BOOL)synchronize;
101
102//
103// Methods for setting, getting, incremeting, and decrementing stats.
104//
105
106// Sets the NSNumber value for the given |stat|.
107- (void)setNumber:(NSNumber *)num forStat:(NSString *)stat;
108
109// Returns the NSNumber value for the given |stat|.
110- (NSNumber *)numberForStat:(NSString *)stat;
111
112// Increments the specified |stat| by 1. If the stat was previously undefined, 
113// it will count as 0, so the first increment will yield a value of 1.
114- (void)incrementStat:(NSString *)stat;
115
116// Increments the specified |stat| by the amount specified by |n|. Setting n = 1
117// is equivalent to calling -incrementStat:. A negative value for |n| is
118// equivalent to decrementing the stat.
119- (void)incrementStat:(NSString *)stat by:(int)n;
120
121// Decrements the specified |stat| by 1. If the stat was previously undefined,
122// it will count as 0, so the first decrement will yield a value of -1.
123- (void)decrementStat:(NSString *)stat;
124
125// Decrements the specified |stat| by the amount specified by |n|. Setting n = 1
126// is equivalent to calling -decrementStat: A negative value for |n| is
127// equivalent to incrementing the stat.
128- (void)decrementStat:(NSString *)stat by:(int)n;
129
130@end