MCache Documentation

  • warning: include(/tmp/fortune.txt): failed to open stream: No such file or directory in /home/mohawksoft/org/www/htdocs/includes/common.inc(1696) : eval()'d code on line 1.
  • warning: include(): Failed opening '/tmp/fortune.txt' for inclusion (include_path='.:/usr/share/php:/usr/share/pear') in /home/mohawksoft/org/www/htdocs/includes/common.inc(1696) : eval()'d code on line 1.

MCache 2.0

The Mohawk Software Shared Cache Server

By Mark L. Woodward

March 3, 2007

Copyright © Mohawk Software 2001, 2007

Introduction

MCache can best be described as a user customizable high performance object oriented data storage server. It is based on MSession which in turn was based on an unnamed data “mailbox” system written for a beowulf parallel processing project. The primary goal of MCache is to store and retrieve “objects” quickly. The latest version of MCache has a lot of features that take it from its humble beginnings to a full fledged enterprise ready system for web cluster synchronization.

Object Data Storage System

MCache is primarily designed to store and retrieve data objects identified by a key. The key can be a user generated string or a pseudo-random unique key generated by MCache. Each object has a key, a class name, and data. Additionally objects may have any number of “name/value” pair attributes assigned to them. The object data is typically retrieved when an object is locked, the name/value pairs can be retrieved or set at any time. The data is stored back in the object when it is “unlocked.”

Synchronization

The MCache daemon provides cooperative object level locking. This mechanism can be used to synchronize access to objects across multiple processes and computers. In a web cluster this is required to eliminate web pages based on “frames” from corrupting session information.

Garbage collection

The MCache daemon also manages garbage collection. In a web environment, more often than not, users leave without formally logging off. It is often difficult to track which sessions that are no longer in use. MCache intelligently tracks the last "access" of session data. At regular intervals, the mcache system scans the active session list for sessions which have not been used within a configurable period of time. When this time has expired, MCache can remove the sessions. If a persistent storage plugin module is used, these removed session can be re-constituted.

Individual sessions can have their own time-out values, independent of the system defaults, this includes, a “no time-out” value, indicating that the session is not to be removed (flushed) or destroyed.

Remote Execution

One of the more interesting features of MCache is the ability to execute arbitrary plugin module code. A developer may create new modules that can augment or even replace standard functionality of MCache. Functions may be disabled by replacing them with non-functional plugin stubs.

Flexibility

MCache, at it's core, is designed around flexibility. It can be a stand-alone unit that doesn't permanently store data or uses the file system to store session information. Using standard plugins, MCache can store session information (both simple and complex) in the file system or in a SQL database.

Quick Start

As a PHP Session Handler

At the simplest level, MCache can be used completely transparently to a PHP application. By editing PHP's “php.ini” file to use MCache as its default session handler (see Appendix D), applications will simply use MCache without knowing. This has an advantage in that MCache presents a standard interface for PHP regardless of it storage configuration. It can even hide which storage system or database is used and provides an amount of connection pooling and SQL caching.

Using the Native API

In addition to the benefits described with using MCache as a PHP session handler, when you use the native API, there are even more advantages. There are three API functions that allow numerical manipulation at the MCache level in order to manage coherency on highly parallel web environment. This is extremely useful for creating high speed counting mechanisms like polls.

C/C++ API

MCache provides a complete C/C++ API mostly analogous to the PHP API. Data stored in PHP can be accessed in C/C++ and vice versa. Internally, MCache stores data as ASCII stings, this allows easy translation from various programming environments.

Other Programming Languages

The availability of both a C API and a C++ class means that many other languages may access MCache.

MCache API

The mcache daemon can be accessed by a few environments. Currently full access to the system is provided for in PHP and C/C++. A more limited access is provided as an extension to PostgreSQL. The API list that follows shows the PHP API first, followed by the C/C++ function declaration. When the C API returns a string or an array of strings, the return value is stable must be freed by the mcache_free(..) function when it is no longer needed, failure to do so will result in memory leaks.

mcache_add(session, name, value)

char *mcache_add(MSCONN conn, char *session, char *name, char *value);

A collision-safe addition method. Used for adding a value to a session's name/value at the mcache level in order to eliminate contention.

mcache_call(fn_name, p1,p2,p3,p4)

int mcache_call_int(MSCONN conn, char *fnname, int n, char **strings);

char *mcache_call_text(MSCONN conn, char *fnname, int n, char **strings);

Calls a user function with a variable number of parameters. The "fn_name" parameter is the name of a function within a function plugin that was loaded at mcache start time. In the C API, strings is an array of string pointers, the first of which is the function name. The int version of the call returns and integer, the text version of the call allocates and returns a string representing the result.

mcache_commit(session)

MSCONN mcache_commit(iMSCONN conn, char *session);

Commits a session to persistent storage system (if any).

Returns nothing.

mcache_connect(host, port)

MSCONN mcache_connect(char *host, int port);

Connects to an mcached host server. If mcache used as the PHP session handler, this call should not be made.

Returns FALSE for failure.

mcache_count()

int mcache_count(MSCONN conn);

Checks the number of active sessions.

Returns the count of sessions.

mcache_create(session, classname, data)

Boolean mcache_create_session(MSCONN conn, char *session, char *classname, char *data);

Creates a cached session. If mcache is used as the PHP session handler, this call should not be made.

Returns FALSE on failure.

mcache_ctl(session, function)

int mcache_ctl(MSCONN conn, char *session, int type);

int mcache_ctl_type(char *str);

The mcache_ctl function is primarily to test if the session value passed exists in the system. If it does, the web programmer has a number of options on the type of data returned. By setting 'function' to one of the following values, the operation of mcache_ctl can be changed.

  • EXIST Returns the server based last access time of the session.

  • TTL "Time To Live," this is the number of seconds before session is flushed, (if unused).

  • AGE Age of the session in seconds.

  • TLA "Time of last Access," number of seconds since last access.

  • CTIME The server creation time of the session

  • TOUCH Sets the last access time of the session to now, and returns current server time.

  • NOW Returns current server time.


The C version of the API accepts an integer which is defined as the above list, but with REQ_CTL_ preceding the function type, as REQ_CTL_EXIST or REQ_CTL_TTL. The mcache_ctl_type(...) function converts a string to a numeric type.

Returns various.

mcache_destroy(session)

Boolean mcache_destroy(MSCONN conn, char *session);

Destroys the session and frees all resources allocated by it. If a persistent storage system is used, the entry for the session is removed.

Returns nothing.

mcache_disconnect()

Boolean mcache_disconnect(MSCONN conn);

Disconnects from an mcached server. (This is called at PHP exit even if you do not call this function.)

Returns nothing.

mcache_exec(command)

char *mcache_exec(char *szcommand)

Executes a command on the MCache server system. (Disabled by default, use execplug).

Returns a string created from stdout of the command.

mcache_find(name, value)

char **mcache_find(MSCONN conn, char *name, char *value);

Finds all the session that have an association between "name" and value of "value." Simply finding a session does not update its last "last use" time for garbage collection.

Returns an array of session strings.

mcache_get(session, name, default)

int mcache_get_int(MSCONN conn, char *session, char *name, int default);

char *mcache_get_text(MSCONN conn, char *session, char *name, char *default);

Gets the value associated with "session" and "name." If no name/value pair is found in session, the default value is returned. When a value is retrieved from a session, its "last use" time is updated.

Returns value or default.

mcache_get_array(session)

char **mcache_get_array(MSCONN conn, char *session);

Gets all name/value pairs in a session. In C/C++ the array of strings returned is organized as follows: string[0] is the name and string[1] is the value, string[2] is the next name and string[3]is the next value, and so on. When values are retrieved from a session, its "last use" time is updated.

Returns an associative array of variables.

mcache_getdata(session)

char *mcache_getdata(MSCONN conn, char *session);

Sessions have a single data string associated with them. When session data is retrieved from a session, its "last use" time is updated. If the session does not exist, it is created. If there is a plugin which handles “PLUGIN_SESSION_INIT” it will be called.

Returns the data string or NULL.

mcache_inc(session, name)

char *mcache_inc_text(MSCONN conn, char *session, char *name);

int mcache_inc_int(MSCONN conn, char *session, char *name);

A collision-safe method of implementing a counter. Similar to a SQL sequence.

Returns the current count. The "last use" time of the session is updated when a variable is incremented.

mcache_list()

char ** mcache_list(MSCONN conn);

Returns an array of all the sessions active on the system. Simply listing sessions does not affect their "last use" time.

Returns an array or NULL for error.

mcache_listclass(classname)

char ** mcache_listclass(MSCONN conn, char *claaname)

Returns an array of sessions for all sessions that of type “classname.” Simply listing sessions does not affect their "last use" time.

Returns an array or NULL for error or none found.

mcache_listvar(name)

char ** mcache_listvar(MSCONN conn, char *name)

Returns an associative array of value:session for all sessions that have a setting of “name.” In C/C++ the array of strings returned is organized as follows: string[0] is the first value name and string[1] is the session name, string[2] is the next value and string[3] is the next session name, and so on. Simply listing sessions does not affect their "last use" time.

Returns an array or NULL for error or none found.

mcache_lock(session, key)

int mcache_lock(MSCONN conn, char *session, int key, char **data);

Sets the lock flag on a session. A lock remains exclusive for an mcached tunable amount of time (30 seconds default), after which time another process can lock the session. Locks are cooperative, i.e. there is no enforcement of locking. Locking a session affects its "last use" time.

Returns session data string or NULL.

mcache_muldiv(session, name, mul, div)

char *mcache_muldiv(MSCONN conn, char *session, char *name, char *mul, char *div);

A collision-safe method for manipulating numerical data in MCache. Used for multiplaying and/or dividing a value at the mcache level in order to eliminate contention.

mcache_plugin(session, nparam, sparam)

int mcache_plugin_int(MSCONN conn, char *session, char *nparam, char *sparam, int param);

char *mcache_plugin_text(MSCONN conn, char *session, char *nparam, char *sparam, int param);

Allows a PHP script to call into an mcache daemon plugin. Input and output are all plugin dependent. The nparam value is intended to be a numerical value to select a plug-in function, the sparam is intended to be a string value for the plugin. All of these values, including the session parameter, are used at the discretion of the plugin.

Returns the value returned by the plugin or FALSE for error.

mcache_randstr(char_count)

Int mcache_randstr(MSCONN conn, int char_count);

Creates a pseudo-random alphanumeric string. Can be used for password generation, encryption, session creation, etc. Since it is created in the mcached server, it is more likely to be a more random than one generated on the individual web server.

mcache_set(session, name, value)

int mcache_set(MSCONN conn, char *session, char *name, char *value);

Inserts a name/value pair for the session. Setting a variable in a session updates its "last use" time.

Returns TRUE on success.

mcache_set_array(session, array)

(PHP only)

Scans the array for all name/value pairs and inserts them in to the session. Setting variables in a session updates its "last use" time.

Returns TRUE on success.

mcache_setdata(session, string)

int mcache_setdata(MSCONN conn, char *session, char *string);

Sets the session data string. Setting data in a session updates its "last use" time.

Returns TRUE for success and FALSE for failure.

mcache_timeout(session,[timeout])

Boolean mcache_timeout(MSCONN conn, char *session, int timeout)

Sets the idle timeout characteristics of a session. If the timeout value is greater than zero, timeout represents the number of seconds a session must be idle before being flushed. If the timeout value is zero, the default configuration of mcached is used (default). If the timeout value is greater than or equal to 65,535 (0xFFFF, 18 days), a session will never be flushed. If timeout is greater than zero, it represents difference (in seconds) between a sessions "last use" time and the current time for eligibility for garbage collection.

Returns TRUE for success and FALSE for failure.

mcache_uniq(char_count, classname, data)

char *mcache_uniq(int charcount, char *classname, char *data)

Creates a guaranteed unique session. The char_count parameter is the number of characters. WARNING!! Too few characters specified by char_count, can make it impossible for this function to work. 16 or more characters should be used. The returned string is a random collection of alphanumeric characters ranging from 0 to 9 and A to Z.

Returns a string to the newly created session's name.

mcache_unlock(session, key, data)

int mcache_unlock(MSCONN conn, char *session, int key, char *data, int cb);

Unlocks a locked session and sets the session data string. The session's "last use" time is set on an unlock. If “commit” is enabled, a session data and all its name/value pairs are written to the persistent storage system.

Returns nothing

MCache Programs

A standard MCache solution has two programs: mcached and madmin. (The tools directory in the source tree has a number other utilities that are userful mostly for developers.)

mcache [-f mcache.cfg]

The mcache program is the MCache server daemon program. It has few options as most configuration is done in the mcache.cfg file.

mcache -f /opt/mohawk/conf/mcache.conf

madmin [options] operation parameter

The madmin program is designed to operate as the main administrators access to MCache. The program sends administration commands to the MCache daemon and can optionally start and stop the system.

AUTOSAVE minutes

madmin autosave 5

Sets the autosave time limit.

CALL funct [paramters]

madmin call myfunction myparameters

Calls a user defined function in the mcache server with optional parameters

COMMIT

madmin commit y

madmin commit n

Enables or disables commit on unlock in mcache server.

FLUSH [time]

madmin flush

Causes mcache to scan through the session table for sessions which have not been used recently and flush them from the system. An administrator can use this to more quickly remove unused sessions when the system is under heavy load.

LOADDLL dllpath

madmin loaddll /opt/mohawk/libexec/fnplug.mcm

Loads a DLL or shared library into the mcache server

PING

madmin ping

Like standard “ping” but sends a MREQ_PING packet to the mcache server and waits for a response. Checks if mcache server is really working.

SETVERBOSE number

madmin setverbose 3

Sets the verbosity of mcache logging

SERIALIZE

madmin serialize

Initializes a “serialize” even in mcache that writes all unsaved sessions to disk.

SHUTDOWN [seconds]

madmin shutdown

Shuts down the mcache server.

START

madmin start

Starts the MCache server with defaults using the mcache.cfg file located in the default dirtectory “conf” directory, typically “/opt/mohawk/conf/mcache.conf”

STOP

madmin stop

Stops the mcache server, a synonym to SHUTDOWN.

STATUS

madmin status

Gets status information from server

Standard Plugins

MCache implements an amount of functionality in the form of external “plugin” modules. Plugins make it easy to change the operation of MCache depending on the needs of deployment.

Execute Plugin

execplug.mcm

Allows the execution of programs remotely. It is not part of the default MCache setup for obvious security reasons. If you use this plugin, you can use mcache_exec to run a program.

Filestore Plugin

filestore.mcm

The file store plugin is the standard persistent storage plugin for MCache. It can commit sessions as directed and can serialize (write to disk) uncommitted session periodically. It uses a data storage directory configured in the mcache.cfg file.

Protection Plugin

protplug.mcm

The protection plugin stubs out the mcache_list, mcache_listvar, and mcache_listclass functions to isolate session location in an environment where multiple independent systems may share a single MCache daemon, as in a mass hosting environment.

SQLCache Plugin

sqlcache.mcm

The SQL cache plugin is similar to the filestore plugin in that it provides a persistent storage for MCache objects except that it uses a SQL database instead of the file system. The SQL Cache Plugin is under development and considered “alpha” code.

Use Cases

Standard RAM only MCache

This is the simplest implementation of an MCache server. MCache is more or less a shared memory session cache.

This usage is intended for highly volatile websites where the session information is used as nothing more than transient state information for the site's users. If they go away, and come back in an hour or so later, a new session will be created. It is assumed that if the mcache daemon is started and stopped, all active session data is lost.

Just start MCache with no options. It will answer session queries without backup or persistence.

Pros:

Very fast.

Cons:

No data backup or persistence.



MCache with the Filestore plugin

This is the next basic step of MCache support. MCache is used like a read/write cache in front of a persistent storage mechanism. Using filestore, the mcache system maintains a disk version of the session information.

Pros:

Very fast.

MCache system can be started and stopped without losing session information.

Cons:

Requires session storage area, must be periodically checked for very old sessions.



SQL Cache with serialization (alpha)

The SQL cache is similar to the file store except that it uses a SQL database to store its data.

Pros:

MCache system can be started and stopped without losing session information.

More standardized data storage.

Cons:

Higher Performance penalty than file store.



Persistant Storage with COMMIT

When file store or SQL cache is used and the COMMIT feature is enabled, sessions are saved to the persistent storage system at the time when mcache_unlock is executed.

Pros:

Reduces risk of data loss.

Cons:

Performance penalty.

Why MCache?

MCache is sort of unique in what it does. It was developed for a specific class of problem that is ill served, a shared cache system that isn't necessarily tied to specific data. To understand what MCache does, you sort of need to understand the construction of a high performance website.

Distribution of Work

A high performance web site attains its performance by distributing the work of the site to a number of computers. This is typically done with a load balancer system. The job of the load balancer is to direct requests sent to a single site to multiple web servers, for more information the Linux Virtual Server (http://www.linuxvirtualserver.org/) has some good information.

Data Access vs Data Processing

One of the biggest traps that inexperienced and not so inexperienced architects make is not understanding the cost of data access. It doesn't matter how many web servers you have serving content if the back-end systems are heavily loaded getting the same data over and over again. Most web sites use a caching system like web sessions to create an aggregate data block of the information constructed at user login.

Appendix A

MCache Daemon Options

The mcache daemon is the core of the mcache system. It is a stand-alone program which answers requests from mcache clients. The MCache daemon is a configuration file to determine the operating characteristics.

Autosave

AUTOSAVE=time

The mcache daemon can call the serialization function on a periodic basis. This allows the daemon to maintain a running backup of session information.

Background Execution

DAEMON=[true][false][1][0]

The mcache program will startup in the background and return immediately.

Commit Sessiosn

COMMIT=[true][false]

When using a persistent storage system, the mcache_unlock function will save the object's data and all its name/value pairs to the storage system.

Data Directory

DATADIR=/var/mcache

The data directory is where MCache storage systems will store their data. Data will be owned by the owner of the MCache process.

Dead Session Timeout

DEAD=timeout

Dead sessions are those sessions that show no activity for a prolonged period of time. This setting allows the default behavior of mcache to be changed. The default is one hour, after which the session and all its data will be deleted.

File Store Hash Size

FS_HASHSIZE=number

The file based persistent storage plugin stores session files in a directory tree in the MCache “Data Directory.” To improve performance, it reduces the number of files in a single directory by calculating a hash number based on the key or session name, and creates the file in a particular sub-directory “bucket.” This improves file access performance.

File Store Hash Sample Size

FS_SAMPLE=number

When the file store system calculates a hash value for an object key, this configuration value limits how many characters are used to calculate the hash. This reduces the amount of processing required to calculate the hash.

Global Session

GLOBALS=globals

A special session, which will never expire, can be created prior to any mcache requests. This is useful for storing information shared between the clustered web servers.

HASH Table Size

HASHSIZE=hashsize

Sessions are stored in a hash table. The size of this table can be adjusted depending on the number of active sessions expected. It is typically a good idea to choose a prime number about twice the number of expected active sessions.

Host Bus Adapter Allow

HBA=netmask/network

This option allows you to specify multiple netmast/network pairs that are allowed to access the mcache daemon. If no HBAs are specified no validation is performed. If HBAs are specified, only those specified will be granted access, all others (including localhost)will be rejected. Multiple HBAs can be specified in the configuration file.

From a security point of view, it is better to have MCache behind a firewall than to rely on HBA entries. The frewall works at the OS or hardware level where as the MCache HBA filtering works at the application level. It is more efficient to reject packets before they get to the application. HBA filtering is provided for sites which do not have firewalls.

Interval for Garbage Collection

INTERVAL=interval

The mcache daemon will clean up all by itself. This specifies how often it scans the active session list for sessions that have not been used within the "Dead Session Timeout" amount of time.

Listener Threads

LIST=numthreads

The mcache daemon is a threaded server. This parameter configures the number of threads initially started in the thread pool. If MCache is being used without any plugin modules, this should be about twich the number of CPUs on your system. If you are using a persistent storage system, you may want to use a few more so MCache can handle read and lock requests while other threads are waiting for I/O.

Lock Timeout Value

LOCK=timeout

The session-locking mechanism needs to be able to recover if a process that has locked a session dies unexpectedly or does not unlock a session. If a locked session is not unlocked within this amount of time, it will be available for locking once again.

Logfile

LOGFILE=/path/filename

Rather than output error and warning messages to the standard error output, redirect them to the logfile

Plugin

PLUGIN=name:module

The mcache daemon allows end users to add callable functions to msesion. These functions are executed on the mcache machine within the mcache process and behave like the other mcache API functions. The are accessed with the mcache_call function.

The name:module syntax provides the ability to have more than one plugin per module. The name portion is defined within the plugin using the FN_ macros. The module must be a full pathname to a shared library (or DLL under Windows). Under UNIX the shared library name may be used if that module is in the LD_LIBRARY_PATH. Under Windows, the DLL can be in the PATH.

Multiple plugins can be specified in the configuration file.

Port for MCache Server

PORT=port

This specifies the port on which the server will listen for requests. There should be no need to change this.

Queue Size for TCP/IP Sockets

QUEUE=backlog

On most server operating systems, the OS creates a queue of client TCP/IP connections that have been accepted but which have not yet been handled by the server program. This behavior varies widely over many platforms. This parameter is used to tune this behavior and is intended for experts only.

On systems with good scheduling response, the default of 128 should be sufficient. If you get connection failures, you may want to increase this value.

Windows users: On any windows system less than a “server” version, the backlog queue is limited to 5. You must Windows (NT,2K, XP) Server or Advanced Server.

SQL Cache Connect String

SQLCACHE_CONNECT=....

The SQLCACHE_CONNECT string is very database specific and uses any number of the following items:

  1. AUTH: This parameter is used by the ODBC SQL object. It is the authorization password for the database connection.

  2. DB: This parameter is used by the SQL object manager to decide which database technology to use. Currently this is ODBC, PGSQL, SQLITE3.

  3. DS: This parameter is the data source. In ODBC terms this is a system DSN. In PostgreSQL terms this is the PostgreSQL database. In SQLITE3, this is the database file.

  4. HOST: This parameter is used by the PostgreSQL object as the host name for the database system. If this is omitted, localhost is assumed.

  5. NAME: This is the user name of which is used to connect to an ODBC database. This parameter combined with “AUTH:” provides the connection credentials.

  6. PORT: This is the port through which a PostgreSQL connection is made.

SQL Driver

SQLDRIVER=/opt/mohawk/libexec/mpgsql.mcm

The SQL driver option loads a SQL driver for use by the SQL Cache persistent storage system, it is identified by the “DB:” parameter int the SQLCACHE_CONNECT string.

Supervisor Mode

SUPERVISOR=[true][false][1][0]

Supervisor mode is a fault tolerant mode where mcache splits in two. The first process does nothing but watch over the second. The second process does the actual service. This feature is a safety net. MCache should not crash, and if it does there is a problem, but bugs do show up every once and a while. External libraries may introduce problems that accumulate over time as well. For these reasons, this feature allows your site to keep operating as best as possible until the issues can be resolved.

Verbose

VERBOSE=verbosity

Verbose execution of mcached is helpful when tuning. Each "-v" on the command line increments a verbose counter. The higher the verbose setting the more debug information is displayed. The mcached program should not be run in verbose mode because it affects performance.

Appendix B

Scalability and Performance

Scalable means that one can grow a system, but what is scalable? There are two ways to think about the term "scalable." (1) Can mcache be set up to work across a cluster of computers? No, the daemon runs on one computer and it provides coherent data for a cluster. (2) Can the mcache daemon take advantage of an SMP computer system? Yes, the mcache daemon was written, debugged, and tested on SMP machines. It should be capable of scaling as high as you can go on a single SMP and threaded core system.

The mcache daemon keeps everything in RAM. As long as you have enough memory installed in your system, the only limitation is the network. If you have only one network card, it is unlikely that you will ever need to get more than one fast processor with lots of RAM.

Since the mcache daemon keeps all active data in RAM, it is extremely fast. Should you be in a position where a single mcache system does not seem to have enough bandwidth there are a number of things you can try first:

Check the number of mcache threads. If you have too few MCache threads, your web cluster will spend time waiting. If you have too many threads, the system will spend more time scheduling the many tasks. Threads can be “busy,” i.e. not answering requests, specially if commit is enabled.

Use "top" or some other performance tool, and look at the load average, system CPU utilization, and user CPU utilization.

If the load average is high, but the system and user CPU utilization is low, it means processes are probably “blocked.” This could mean that you have a lot of network traffic on your system. Check to make sure that all your systems are functioning properly and that they are interconnected with a high quality ethernet switch. Alternatively it could be a plugin blocking on you, make sure that you double check your plugins for ones that will wait.

If the load average is high, the system CPU utilization is high, but the user CPU utilization is low, this may indicate that the network card, or its driver, in the mcache server system is not very efficient. Cards like NE2000 compatible NICs do more work in the driver than do cards like the 3Com 3c905.

If there are no obvious problems, and your MCache server is really at capacity, you will need to use a hybrid approach. By using a two or more MCache servers and using the load balancer to split your traffic among smaller clustered groups, you can provide more capacity.

Appendix C

Reliability and Redundancy

Is mcache redundant? No. However, much of the technology on which mcache is based is working on many systems with a long-term 24x7 uptime. It has been checked extensively for memory leaks, and single instances have been tested with over 1.5 billion full session uses (tools/loadtest). The mcached daemon can be configured to save and restore its state at startup and shutdown, as well as periodically while running (the autosave and commit options). The storage system may be on an NFS share or SQL database which can be used by a “hot spare” MCache daemon in the event of falure.

Appendix D

Using MCache in PHP

The PHP mcache extension will also work with the PHP session handler seamlessly. The mcache extension can be just another "save handler" for PHP sessions, configurable through php.ini.

[Session]

; Use mcache as the save handler

session.save_handler = mcache

; Set the host which runs the mcache daemon

session.save_path = localhost

Unfortunately, the PHP session data is only accessible as the raw string written by the PHP session extension, the format of the string is not rigidly defined and is subject to changes. This means that the extra functionality provided by the mcache daemon is only available when using mcache data values. The standard PHP session API and the mcache API are not mutually exclusive, you can use standard PHP sessions and use the function session_id() function to acquire the session name which can be used with the mcache functions.

Also, Mohawk Software has the xmldbx extension for PHP which reads and writes PHP session data in standardized format XML stream.

Simply by creating a convention that all sessions have a common name/value pair, with the name of "user" and the value being set to he user's name, allows users with active sessions to be found or listed easily.

64 Bit

We have a 64 bit development/evaluation system on order and it is coming soon. The plan is to evaluate the system and Linux distributions, then buy a number of systems for our internet data center. Since the site runs MCache, MCache *will* run on 64bit.

Don't use the msession extension provided by PHP, use the one available in the MCache distribution as the PHP version is no longer supported.

re: madmin compile error

You should add -DSBINDIR=somedir to the compile line, that should be there.

As for old version of MCache/MSession, I'm sure you can get it out of CVS, but the PHP extension has been dropped from the PHP project and I doubt it even compiles.

If it is any reassurance, the current beta (6 at the moment) ALWAYS runs this site. If this site doesn't run, it isn't good enough to be a beta.

not an error

Technically speaking that's a warning not an error. It's OK.

Binary Data

Some work has been made to store binary data in the sessions, but right now it assumes null terminated strings.

I haven't seen binary data come from PHP before because the serializer typically takes care of it before calling PS_WRITE_FUNC to save the session info. I wonder if this is new with 5.1?

Beta Software

For MCache there is a program that is not currently in this beta but which will be included next beta. The program is mfsvacuum which scans the file store directory structure and finds session files which will be deleted.

The big issue being struggled with, as we speak, is the difference between a session that has "gone away" and may come back, and a session that should be deleted.

The idea that we should actively delete sessions so as they will not be recreated is new as of your comment. Most all suggestions have requested more long-term storage.

A new configuration parameter has been added, "EXPIRE," will direct mfsvacuum to delete sessions that have exceeded the expiration time.

The next beta, due out before May (fingers crossed) will contain mfsvacuum which should take care of your issue.

PHP-5.2.0?

I haven't even looked at 5.2 yet. I've been very busy getting 2.0 wrapped up.

I'll download it and see what's up.

Did you try loading MCache as a module?

64 Bit

We currently do not have any 64 bit machines in house. We are planning a migration later in the year, but we have not as of yet begun the process. Mohawk Software is currently focusing on its "for profit" development.

There are a few issues that are known in mcache and phoenix having to do with system integer type widths, size_t vs int sort of stuff, but AFAIK nothing major.

If Mohawk Software gets a contract that requires 64 bit hardware, then MCache's 64 bit development could start sooner rather than later as "phoenix" is typically used in many projects.

I know that's not the answer you wanted to hear, but there are financial realities that require prioritization, and 64 bit isn't there yet unless someone wishes to fund it.

Read INSTALL

A new file, INSTALL, was added.