Introduction

This chapter describes the basic structure of TCache and how to configure it.

1. Overview

ProFrame provides TCache for cache processing. TCache caches data obtained from a database during ProFrame operation in shared memory. Since this reduces overhead of accessing the database whenever there is a database data request, the performance of ProFrame improves.

TCache queries and loads data from a database only when the data does not exist in shared memory. If the data is modified after the loading, it can be synchronized with the database by using the invalidation function.

The following shows the basic structure of TCache.

figure1 1
TCache Structure

  • pfmtcacheadmin

    Controls basic functions. It creates, initializes, deletes, and monitors TCache and checks a caching report.

  • pfmTCache.cfg

    Environment configuration file. It specifies a shared memory address, privileges, the memory size, the hash table size, the hash key size, the data size to cache.

  • libpfmTCache.so

    TCache library with compiled functions to call. To use TCache, it must be linked when user source code is compiled.

  • TPFMAGENT

    Tmax server for the invalidation function that synchronizes data when TCache is configured in multiple nodes.

For TCache performance, use TCache for data on which a write operation does not frequently occur.

2. Environment Configuration

pfmtcache.cfg is TCache configuration file with information about shared memory structure.

The file is located in the following directory by default. It can vary depending on the installation directory.

$PRJROOT/package/proframe/pfm/cfg/pfmtcache.cfg

The configuration file is as follows:

########################
# Common Area
########################
SHMKEY      = [shared-memory-key]
IPCPREM     = [shared-memory-permission]
SIZE_LOCAL  = [cache-size]
LIB_PTHREAD = [file-name]
INVALIDATE_TYPE = [invalidate-type]
AGENT_SVC = [agent_service] 

########################
# Individual Area
########################
CACHE_NAME = [chache-name]
SIZE_MEM   = [chache-memory-size]
SIZE_HASH  = [hash-key-size]
SIZE_KEY   = [key-size]
SIZE_REC   = [record-size]
INV_TIMEOUT= [timout-sec]
CALLBACK_NAME= [callback-name]
Item Description

SHMKEY

ID of shared memory in Unix.

IPCPREM

Permission for shared memory.

SIZE_LOCAL

Maximum size of data (records) recorded in a server process. (Unit: KB)

LIB_PTHREAD

Unused. Currently, only a symbolic link is used.

INVALIDATE_TYPE

Invalidation type. Refer to TCache Synchronization.

AGENT_SVC

Server that invalidates data. Refer to TCache Synchronization.

CACHE_NAME

Cache name.

SIZE_MEM

Size of shared memory allocated for the cache name. (Unit: KB)

If this size is exceeded, the least recently used algorithm is used.

SIZE_HASH

Hash key range.

SIZE_KEY

Length of a search key value.

For example, when the key is 10 bytes and data is a 90-byte structure (struct { char Key[10]; char Data[90]; }), set this item to 10.

Exceptionally, when several members compose one key, the length can be different from simple summation because of padding bits. To set the exact key length, use sizeof on the key structure.

SIZE_REC

Size of a slot that is a minimum unit to allocate memory.

For example, when the key is 10 bytes and data is a 90-byte structure (struct { char Key[10]; char Data[90]; }), set this item to 100.

Exceptionally, when several members compose one record, the length can be different from simple summation because of padding bits. To set one record for one slot, set this item by using sizeof on the structure to get. If a record that is put exceeds this item value, it is divided in the unit set in this item and saved to slots.

Set the size of a temporary buffer used to get data used in API.

INV_TIMEOUT

Period of time to prohibit a put operation after invalidation.

CALLBACK_NAME

Business module for search for the case that pfmTCacheItem fails to perform the get operation.

This item is used for business modules of ProFrame C because of its internal processing structure. If the physical name of a business module is GET_PFM_SVC, a library file is created with the name of libGET_PFM_SVC.so. Set this item to the physical name.

CALLBACK_NAME=GET_PFM_SVC

The following is a sample file.

# the configuration file of TCACHE
SHMKEY=0x70056             # the key of shared memory
IPCPERM=0777               # permission of the shared memory
SIZE_LOCAL=1024            # L1 cache size in kilobytes
LIB_PTHREAD=libpthread.so  # the pthread library file name
#INVALIDATE_TYPE=1         # Invalidation type 0: multi-node, 1: multi-domain
#AGENT_SVC=SPFMAGENT|2     # multi-node sync. svc SPFMAGENT|2 = SPFMAGENT01, SPFMAGENT02

# cache for PFM_SVC
CACHE_NAME=PFM_SVC
SIZE_MEM=65536             # the total cache memory size in kilobytes
SIZE_HASH=1024             # the number of hash key (MAX=6553)
SIZE_KEY=30                # the number of digits of the index column
SIZE_REC=2048              # the size of a single record in bytes
INV_TIMEOUT=10             # invalidation timeout in sec
#CALLBACK_NAME=GET_PFM_SVC # callback func name (libGET_PFM_SVC.so)