Where other cache servers fail by not providing the application enough control over its data, Bullet cache offers a unique interface, record tags, which enables complex interactions between the application and its cached data.
Records stored in the cache server are composed from the following user-visible pieces of data:
- Key
- Data
- Expiry time
- Tags
These constituents of cached records are discussed in the following sections.
Record keys
Record keys are binary safe (i.e. can contain absolutely any byte values) strings of maximum length 65,534 bytes (in other words, almost 64 KiB). Each time a record key is referenced, it is referenced together with its length field. There are no other restrictions on the composition of record keys.
Record data
Record data is an arbitrary, binary-safe string of maximum length 2,147,483,646 bytes (in other words, almost 2 GiB). Each time record data is referenced, it is referenced together with its length field. There are no other restrictions on the composition of record data, but implementors should keep in mind that laws of physics don't really favor caching of records larger than a couple of megabytes.
Record expiry time
Record expiry time is an integer (time_t) representing the classic Unix timestamp, the number of seconds since the Unix epoch. On entry into the cache server, expiry timestamps are interpreted in one of the following ways, depending on their absolute values:
- If the timestamp is 0, it is automatically converted to the largest possible timstamp, representing effective infinity (i.e. the record does not automatically expire).
- If the timestamp is between 0 and REL_TIME_CUTOFF (usually 2592000), it is interpreted as relative to the current server time, and adjusted accordingly (this format allows the quick specification of short expiry times).
- Otherwise, the timestamp is interpreted as an absolute Unix timestamp, in the timezone of the server.
On exit from the cache server (i.e. record retrieval), the original, client-specified timestamp value is returned.
Tags
Record tags are one of the most important features of Bullet cache. They are a simple but highly efficient way to assign user-defined metadata to records, allowing large-scale bulk operations like retrieval and record expiry.
Record tags have a very strict structure for reasons of efficiency. They are themselves key-value pairs where both key and the value are 32-bit signed integers. A cache record can have an arbitrary number of arbitrary tags assigned to it, and Both the tag key and the tag value are independant, opaque integers as far as the cache server is concerned.
If properly used, record tags can have a huge influence on the efficiency and flexibility of the applications' interaction with the cache server. Among others, Bullet cache implements the following multiple-data instructions which act on the record tags (described semantically in a SQL-like way):
- GET RECORDS WHERE tag_key=... AND tag_values IN (...)
- DELETE RECORDS WHERE tag_key=... AND tag_values IN (...)
See Recommendations for application architecture for suggestions on how to make the most use of record tags.
