README
¶
Please note: this package is still in early development. It is in use in production environments and working well, but the API may change at any point without notice.
This package uses SemVer to manage release versions. As of now, the version is < 1.0.0, and point changes may include breaking changes. It is recommended you use dep to vendor your code and lock on a specific version if breaking changes are unacceptable.
Introduction
cache provides a clean, easy to use layer on top of a caching store, such as redis or memcached.
Usage
Please refer to the documentation for additonal information.
Getting started is as simple as:
var pool redis.Pool // make sure you initialize this!
c, err := cache.NewClient(redis.New(pool), true) // pass true to enable gzipping of data before sending to backer
defer c.Close()
c.Set("key", "value")
var out string
err = c.Get(key, &out)
if err == nil {
// got it!
} else if err == cache.ErrNotFound {
// wasn't in cache!
} else {
// some other error occurred
}
Notes
The Set* and Get methods use the json package to marshal and unmarshal objects. This was done for the sake of simplicity and consistency across different backers. Any object you pass to Set* will be marshalled to a json representation. Pass a reference to the same type of object to Get and it will be populated in the same manner as json.Unmarshal.
Contributing
Issues, PRs and discussion are welcome and encouraged, but please follow these guidelines:
Issues
- Please ensure that your issue provides a solid reproduction case so that the problem can be found and a test written to prove its existence.
- If you would like to provide a PR with a test proving the existence of the issue, that would be even better!
- If your issue is a feature request, please provide a solid example of your use case so the request can be discussed appropriately.
- If your request is a breaking change, much more discussion will be involved.
Pull Requests
- Before opening a PR, open an issue with either your problem or your request so that it can be discussed.
- A PR should close the issue you opened.
- All PRs must have accompanying tests. See redis_test.go as an example.
Backers
Currently, only the redis backer is available. However, the Backer interface is open for everyone to use to create whichever implementation they need for their particular use case.
If you have need of a different backing store, please feel free to open an issue for discussion. PRs are encouraged and welcomed.
Documentation
¶
Index ¶
- Variables
- type Backer
- type Client
- func (self *Client) Close()
- func (self *Client) Delete(key string) error
- func (self *Client) Exists(key string) (bool, error)
- func (self *Client) Get(key string, target interface{}) (bool, error)
- func (self *Client) Health() error
- func (self *Client) Set(key string, value interface{}) error
- func (self *Client) SetExpires(key string, value interface{}, expires time.Duration) error
- func (self *Client) UpdateExpiration(key string, expires time.Duration) error
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidExpirationTime is returned when an invalid expiration time is // provided to SetExpires ErrInvalidExpirationTime = errors.New("expiration time must be greater than 0") )
Functions ¶
This section is empty.
Types ¶
type Backer ¶
type Backer interface {
// Set sets a value in the backing store.
Set(key string, value []byte) error
// SetExpires sets a value in the backing store that will expire after the
// duration.
SetExpires(key string, value []byte, expires time.Duration) error
// UpdateExpiration sets the expiration for the key. This is useful for updating
// the expiration value of a key that was recently accessed.
UpdateExpiration(key string, expires time.Duration) error
// Get gets a value from the backing store.
Get(key string) ([]byte, bool, error)
// Delete deletes a value from the backing store.
Delete(key string) error
// Exists returns whether a value exists in the backing store. Returns
// ErrNotFound if it does not.
Exists(key string) (bool, error)
// Health returns the health status of the backer.
Health() error
// Close closes the Backer, shutting down any background processes and blocking
// until shutdown is complete.
Close()
}
Backer is an interface defining methods through which a backing store will handle caching and retrieval of data.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client allows for a simple caching interface into any available backing store.
func NewClient ¶
NewClient returns a new caching client configured with your fully-initialized remote backing store.
func (*Client) Close ¶
func (self *Client) Close()
Close closes the client, shutting down any background processes and blocking until shutdown is complete.
func (*Client) Exists ¶
Exists checks to see if the object exists in the cache.
Returns false, nil if the key does not exist.
func (*Client) Get ¶
Get retrieves a value from the cache and populates the target with the result.
Returns ErrNotFound if the key was not present in the cache.
func (*Client) Health ¶ added in v0.0.4
Health returns the current health status of the backer.
Possible return values are:
nil - no issues non-nil error - error reported by the backer
func (*Client) SetExpires ¶
SetExpires sets a value in the cache with the associated expiration time. The minimum resolution for this expiration time is milliseconds.
Source Files
Directories