sm
/
cache
1
0
Fork 0
Code

Keep the same tense in docstrings, and remove a little ambiguity

This commit is contained in:
Patrick Mylund Nielsen 2012-06-22 04:24:48 +01:00
parent 8f6294df58
commit 0a962bf9eb
2 changed files with 31 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
README
View File

@ -92,28 +92,28 @@ foo.Println(foo.Num)
== Reference == Reference
func New(de, ci time.Duration) *Cache func New(de, ci time.Duration) *Cache
Returns a new cache with a given default expiration duration and cleanup Return a new cache with a given default expiration duration and cleanup
interval. If the expiration duration is less than 1, the items in the cache interval. If the expiration duration is less than 1, the items in the cache
never expire (by default), and must be deleted manually. If the cleanup never expire (by default), and must be deleted manually. If the cleanup
interval is less than one, expired items are not deleted from the cache interval is less than one, expired items are not deleted from the cache
before their next lookup or before calling DeleteExpired. before their next lookup or before calling DeleteExpired.
func (c *Cache) Set(k string, x interface{}, d time.Duration) func (c *Cache) Set(k string, x interface{}, d time.Duration)
Adds an item to the cache, replacing any existing item. If the duration is Add an item to the cache, replacing any existing item. If the duration is
0, the cache's default expiration time is used. If it is -1, the item never 0, the cache's default expiration time is used. If it is -1, the item never
expires. expires.
func (c *Cache) Add(k string, x interface{}, d time.Duration) error func (c *Cache) Add(k string, x interface{}, d time.Duration) error
Adds an item to the cache only if an item doesn't already exist for the Add an item to the cache only if an item doesn't already exist for the
given key, or if the existing item has expired. Returns an error if not. given key, or if the existing item has expired. Returns an error if not.
func (c *Cache) Replace(k string, x interface{}, d time.Duration) error func (c *Cache) Replace(k string, x interface{}, d time.Duration) error
Sets a new value for the cache item only if it already exists. Returns an Set a new value for the cache key only if it already exists. Returns an
error if it does not. error if it does not.
func (c *Cache) Get(k string) (interface{}, bool) func (c *Cache) Get(k string) (interface{}, bool)
Gets an item from the cache. Returns the item or nil, and a bool indicating Get an item from the cache. Returns the item or nil, and a bool indicating
whether the given key was found in the cache. whether the key was found.
func (c *Cache) Increment(k string, n int64) error func (c *Cache) Increment(k string, n int64) error
Increment an item of type int, int8, int16, int32, int64, uintptr, uint, Increment an item of type int, int8, int16, int32, int64, uintptr, uint,
@ -136,28 +136,28 @@ func (c *Cache) Decrement(k string, n int64) error
possible to decrement it by n. possible to decrement it by n.
func (c *Cache) Delete(k string) func (c *Cache) Delete(k string)
Deletes an item from the cache. Does nothing if the item does not exist in Delete an item from the cache. Does nothing if the key does not exist in the
the cache. cache.
func (c *Cache) DeleteExpired() func (c *Cache) DeleteExpired()
Deletes all expired items from the cache. Delete all expired items from the cache.
func (c *Cache) Flush() func (c *Cache) Flush()
Deletes all items from the cache. Delete all items from the cache.
func (c *Cache) Save(w io.Writer) error func (c *Cache) Save(w io.Writer) error
Writes the cache's items (using Gob) to an io.Writer. Returns an error if Write the cache's items (using Gob) to an io.Writer. Returns an error if
the serialization fails, e.g. because there are unserializable objects like the serialization fails, e.g. because there are unserializable objects like
channels in the cache. channels in the cache.
func (c *Cache) SaveFile(fname string) error func (c *Cache) SaveFile(fname string) error
Saves the cache's items to the given filename, creating the file if it Save the cache's items to the given filename, creating the file if it
doesn't exist, and overwriting it if it does. doesn't exist, and overwriting it if it does.
func (c *Cache) Load(r io.Reader) error func (c *Cache) Load(r io.Reader) error
Adds (Gob-serialized) cache items from an io.Reader, excluding any items Add (Gob-serialized) cache items from an io.Reader, excluding any items
that already exist in the current cache. with keys that already exist in the current cache.
func (c *Cache) LoadFile(fname string) error func (c *Cache) LoadFile(fname string) error
Loads and adds cache items from the given filename, excluding any items Loads and adds cache items from the given filename, excluding any items
that already exist in the current cache. with keys that already exist in the current cache.

33
cache.go
View File

@ -36,7 +36,7 @@ type cache struct {
janitor *janitor janitor *janitor
} }
// Adds an item to the cache, replacing any existing item. If the duration is 0, // Add an item to the cache, replacing any existing item. If the duration is 0,
// the cache's default expiration time is used. If it is -1, the item never // the cache's default expiration time is used. If it is -1, the item never
// expires. // expires.
func (c *cache) Set(k string, x interface{}, d time.Duration) { func (c *cache) Set(k string, x interface{}, d time.Duration) {
@ -62,8 +62,8 @@ func (c *cache) set(k string, x interface{}, d time.Duration) {
} }
} }
// Adds an item to the cache only if an item doesn't already exist for the given // Add an item to the cache only if an item doesn't already exist for the given
// key, or if the existing item has expired. Returns an error if not. // key, or if the existing item has expired. Returns an error otherwise.
func (c *cache) Add(k string, x interface{}, d time.Duration) error { func (c *cache) Add(k string, x interface{}, d time.Duration) error {
c.mu.Lock() c.mu.Lock()
_, found := c.get(k) _, found := c.get(k)
@ -76,7 +76,7 @@ func (c *cache) Add(k string, x interface{}, d time.Duration) error {
return nil return nil
} }
// Sets a new value for the cache item only if it already exists. Returns an // Set a new value for the cache key only if it already exists. Returns an
// error if it does not. // error if it does not.
func (c *cache) Replace(k string, x interface{}, d time.Duration) error { func (c *cache) Replace(k string, x interface{}, d time.Duration) error {
c.mu.Lock() c.mu.Lock()
@ -90,8 +90,8 @@ func (c *cache) Replace(k string, x interface{}, d time.Duration) error {
return nil return nil
} }
// Gets an item from the cache. Returns the item or nil, and a bool indicating // Get an item from the cache. Returns the item or nil, and a bool indicating
// whether the given key was found in the cache. // whether the key was found.
func (c *cache) Get(k string) (interface{}, bool) { func (c *cache) Get(k string) (interface{}, bool) {
c.mu.Lock() c.mu.Lock()
x, found := c.get(k) x, found := c.get(k)
@ -177,8 +177,7 @@ func (c *cache) Decrement(k string, n int64) error {
return c.Increment(k, n*-1) return c.Increment(k, n*-1)
} }
// Deletes an item from the cache. Does nothing if the item does not exist in // Delete an item from the cache. Does nothing if the key is not in the cache.
// the cache.
func (c *cache) Delete(k string) { func (c *cache) Delete(k string) {
c.mu.Lock() c.mu.Lock()
c.delete(k) c.delete(k)
@ -189,7 +188,7 @@ func (c *cache) delete(k string) {
delete(c.Items, k) delete(c.Items, k)
} }
// Deletes all expired items from the cache. // Delete all expired items from the cache.
func (c *cache) DeleteExpired() { func (c *cache) DeleteExpired() {
c.mu.Lock() c.mu.Lock()
for k, v := range c.Items { for k, v := range c.Items {
@ -200,7 +199,7 @@ func (c *cache) DeleteExpired() {
c.mu.Unlock() c.mu.Unlock()
} }
// Writes the cache's items (using Gob) to an io.Writer. // Write the cache's items (using Gob) to an io.Writer.
func (c *cache) Save(w io.Writer) (err error) { func (c *cache) Save(w io.Writer) (err error) {
enc := gob.NewEncoder(w) enc := gob.NewEncoder(w)
@ -216,7 +215,7 @@ func (c *cache) Save(w io.Writer) (err error) {
return return
} }
// Saves the cache's items to the given filename, creating the file if it // Save the cache's items to the given filename, creating the file if it
// doesn't exist, and overwriting it if it does. // doesn't exist, and overwriting it if it does.
func (c *cache) SaveFile(fname string) error { func (c *cache) SaveFile(fname string) error {
fp, err := os.Create(fname) fp, err := os.Create(fname)
@ -226,8 +225,8 @@ func (c *cache) SaveFile(fname string) error {
return c.Save(fp) return c.Save(fp)
} }
// Adds (Gob-serialized) cache items from an io.Reader, excluding any items that // Add (Gob-serialized) cache items from an io.Reader, excluding any items with
// already exist in the current cache. // keys that already exist in the current cache.
func (c *cache) Load(r io.Reader) error { func (c *cache) Load(r io.Reader) error {
dec := gob.NewDecoder(r) dec := gob.NewDecoder(r)
items := map[string]*Item{} items := map[string]*Item{}
@ -243,8 +242,8 @@ func (c *cache) Load(r io.Reader) error {
return err return err
} }
// Loads and adds cache items from the given filename, excluding any items that // Load and add cache items from the given filename, excluding any items with
// already exist in the current cache. // keys that already exist in the current cache.
func (c *cache) LoadFile(fname string) error { func (c *cache) LoadFile(fname string) error {
fp, err := os.Open(fname) fp, err := os.Open(fname)
if err != nil { if err != nil {
@ -253,7 +252,7 @@ func (c *cache) LoadFile(fname string) error {
return c.Load(fp) return c.Load(fp)
} }
// Deletes all items from the cache. // Delete all items from the cache.
func (c *cache) Flush() { func (c *cache) Flush() {
c.mu.Lock() c.mu.Lock()
c.Items = map[string]*Item{} c.Items = map[string]*Item{}
@ -286,7 +285,7 @@ func stopJanitor(c *Cache) {
c.janitor.Stop() c.janitor.Stop()
} }
// Returns a new cache with a given default expiration duration and cleanup // Return a new cache with a given default expiration duration and cleanup
// interval. If the expiration duration is less than 1, the items in the cache // interval. If the expiration duration is less than 1, the items in the cache
// never expire (by default), and must be deleted manually. If the cleanup // never expire (by default), and must be deleted manually. If the cleanup
// interval is less than one, expired items are not deleted from the cache // interval is less than one, expired items are not deleted from the cache