happyfish100/libshmcache

Copyright (C) 2016 Happy Fish / YuQing

libshmcache may be copied or modified under the terms of BSD License.

libshmcache is a local share memory cache for multi processes. it is a high performance library because read mechanism is lockless. libshmcache is 100+ times faster than a remote interface such as redis.

this project contains C library, PHP extension and Java JNI wrapper.

Its high performance features include:

• pthread mutex lock on write, read is lockless
• use hash table for quickly setting, getting and deletion
• use object pool (FIFO queue) for hash/KV entry allocation
• use striping/block buffer allocator. in a memory striping, allocate value buffer in order. just only decrease allocator's used size when free the value buffer. recycle the whole memory striping/allocator when it's used size reach to zero after memory free up.
• use FIFO elimination algorithm instead of LRU

stable features are:

• deadlock detection and auto unlock that caused by other crushed process
• check some key fields for consistency when init, old share memories should be cleaned and reinit when the memory related parameters changed
• add sleep time to avoid other processes reading dirty data when recycle more than one valid (not expired) hash/KV entries

other features are:

• support both related processes (such as parent process and subprocesses) and unrelated processes (such as php-fpm and php CLI, two php CLI processes, etc.)
• incrementally allocate value buffer segment as need, this is controlled by config parameter: segment_size
• provide abundant stats info: counters for set, get and delete, memory recycle stats, lock stats etc.
• support atomic increment
• PHP extension support multiple serializers: igbinary, msgpack, php. these serializers can coexist in a share memory.

utility commands in directory: src/tools, in /usr/bin/ after make && make install

• shmcache_set: set a key

• shmcache_get: get a key

• shmcache_delete: delete a key

• shmcache_remove_all: remove the share memory

• shmcache_stats: show share memory statistics

• Note: the key size can not be longer than 64 bytes

libshmcache PHP extension is supplied in the directory: php-shmcache, support PHP 5 and PHP 7

ShmCache::__construct(string $config_filename[, long $serializer = ShmCache::SERIALIZER_IGBINARY])

• @param config_filename: the config filename as conf/libshmcache.conf
• @param serializer: the serializer type

    ShmCache::SERIALIZER_IGBINARY for igbinary, the default serializer
    ShmCache::SERIALIZER_MSGPACK for msgpack
    ShmCache::SERIALIZER_PHP for php serializer
  

• @throws ShmCacheException if the serializer not enabled
• @example: $cache = new ShmCache("/etc/libshmcache.conf");
• @note: igbinary and msgpack php extensions must be enabled before use them

  check method:
  php -m | grep igbinary
  php -m | grep msgpack
  

boolean ShmCache::set(string $key, mixed $value, long $ttl)

• @param key: the key, must be a string variable
• @param value: the value, any php variable
• @param ttl: timeout / expire in seconds, such as 600 for ten minutes, ShmCache::NEVER_EXPIRED for never expired
• @return true for success, false for fail
• @throws ShmCacheException if $value is false
• @example: $cache->set($key, $value, 300);

long ShmCache::incr(string $key, long $increment, long $ttl)

• @desc: atomic increment
• @param key: the key, must be a string variable
• @param increment: the increment integer, can be negative, such as -1
• @param ttl: timeout / expire in seconds, such as 600 for ten minutes,
• @return the value after increase, false for fail

mixed ShmCache::get(string $key[, boolean $returnExpired = false])

• @param key: the key, must be a string variable
• @param returnExpired: if return expired key / value
• @return mixed value for success, false for key not exist or expired
• @example: $value = $cache->get($key);

long ShmCache::getExpires(string $key[, boolean $returnExpired = false])

• @desc: get expires time as unix timestamp
• @param key: the key, must be a string variable
• @param returnExpired: if return expired key / value
• @return expires timestamps such as 1483952635, 0 for never expired, false for not exist
• @example: $value = $cache->getExpires($key);

boolean ShmCache::setExpires(string $key, long $expires)

• @param key: the key, must be a string variable
• @param expires: expires timestamp (unix timestamp eg. 1591347245) ShmCache::NEVER_EXPIRED for never expired
• @return true for success, false for key not exist or expired or other error
• @throws ShmCacheException if $expires is invalid
• @example: $cache->setExpires($key, 1591347245);

boolean ShmCache::setTTL(string $key, long $ttl)

• @param key: the key, must be a string variable
• @param ttl: timeout / expire in seconds, such as 600 for ten minutes, ShmCache::NEVER_EXPIRED for never expired
• @return true for success, false for key not exist or expired or other error
• @throws ShmCacheException if $ttl is invalid
• @example: $cache->setTTL($key, 300);

boolean ShmCache::delete(string $key)

• @param key: the key, must be a string variable
• @return true for success, false for fail
• @example: $cache->delete($key);

array ShmCache::stats()

• @return stats array
• @example: echo json_encode($cache->stats(), JSON_PRETTY_PRINT);

boolean ShmCache::clear()

• @desc: clear hashtable to empty. use this function carefully because it will remove all keys in cache
• @return true for success, false for fail