Class interface to SCACHE's session management

Class interface is later extension to scached module.

API documentation is written from aspect of scache_* -procedural API with comments regarding class interface where necessary. Generally methods and theirs counterpart functions are operationally equal. Differences are on how backend is contacted.

Class constructor

• SCache() constructor and connection to scached backend

Session operations.

Functions for session initialization, opening, connecting, renaming and dropping. Sessions are distinguished and opened by client generated session identifier.

• ->open open existing session
• ->reset reset session's contents
• ->getindex get index of backends session slot for fast connections above
• ->status verify session's validity
• ->rename rename session to new identifier
• ->drop destroy session from backend

Private session storage

Session storage is private save space unique to every session. Session storage is persistent over lifespan of session. Generally session storage is for keeping per user private information and collected per user data sensitive to active login.

• ->get get session specific value
• ->set set session specific value
• ->add add value to session if key doesn't previously exist
• ->replace replace session specific already existing value
• ->clear unset session's value
• ->exists verify existence of session's path
• ->stat query path's type on session table
• ->coll collect and store path's subkeys on session table
• ->move atomically rename and move path

Shared counters

Shared counters are path/key addressable atomic 64-bit integers on scached backend common to all sessions assigned on same partition. Shared counters can be generally used for inter session communication, specifically as advisory triggers.

• ->vadd increment all client shared counter
• ->vsub decrement all client shared countet
• ->vget get value of all client shared counter
• ->vset set value of all client shared counter
• ->vclear delete value of all client shared counter

Shared storage

Shared storage equals to private session storage, but is common and mutually accessible to all sessions residing on same partition. Unlink cache storage described below shared storage never expires stored data until deliberately ordered to. Shared storage can be used for inter session communication with optional aid of shared counters.

• ->shget get path's value from all client shared tree
• ->shset set path's value on all client shared tree
• ->shadd add value to path on all client common storage if value does not exist
• ->shreplace replace value to path on all client common storage
• ->shclear delete path entry from all client common storage
• ->shexists test existence of path on all client common storage
• ->shstat query path's nodetype on all client common storage
• ->shcoll collect and store path's subkeys on all client common storage
• ->shmove atomically rename and move path

Cache operations

Cache storage is path/key addressable shared storage common to alle sessions on same partition. Unlike shared storage above, cache expires data exceeding configurable memory limit.

• ->chput put value to all client common storage
• ->chget get value from all client common storage
• ->chclear remove value from all client common storage

Ring operations

Ring storage is double linked circular datatype on scached backend. As like other data operations, rings are addressed by path-prefixed keys. Each key contains one ring, which can be operated with functions below.

Rings are shared resource common to all connecting clients assigned to same partition. Values stored to rings are persistent. All data queued to ring must be eventually purged to avoid memory leaking.

Rings are mainly for implementing FIFOs, LIFOs and producer-consumers -workqueues.

• ->rnpush push values as last element to ring
• ->rnunshift push values as firt element to ring
• ->rnpop get and remove from end of ring
• ->rnshift get and remove from begin of the ring
• ->rnget poll rings current value
• ->rnrotf rotate ring forward
• ->rnrotb rotate ring backward
• ->rnsize return current size of ring
• ->rnclear clear contents of ring

Misc functions

Miscellaneous utility functions.

• ->getopt get session's options
• ->setopt set session's options
• ->srvstats query for backend's statistics
• ->lasterr return session's latest error code
• ->strerror map error code to string
• ->iov the swiss-army knife

Exception classes

• SCacheException() is thrown on failure to initialize SCache object