Starting Up, Shutting Down, Thread Context
[SHORE Storage Manager Application Programming Interface (SSM API)]

Collaboration diagram for Starting Up, Shutting Down, Thread Context:

Detailed Description

Starting a Storage Manager

Starting the Storage Manager consists in 2 major things:

No more than one instance may exist at any time.

Storage manager functions must be called in the context of a run() method of an smthread_t.

See Examples of Server Code for an example of how this is done.

See also Handling Log Space and Running Out of Log Space for discussions relating to the constructor and its arguments.

Shutting Down a Storage Manager

Shutting down the storage manager consists of deleting the instance of ss_m created above.

The storage manager normally shuts down gracefully; if you want to force an unclean shutdown (for testing purposes), you can do so. See ss_m::set_shutdown_flag.

Handling Log Space

The storage manager contains a primitive mechanism for responding to potential inability to rollback or recover due to lack of log space. When it detects a potential problem, it can issue a callback to the server, which can then deal with the situation as it sees fit. The use of such a callback mechanism is entirely optional.

The steps that are necessary are:

The initial value of the victim parameter is the transaction that is attached to the running thread. The callback function might choose a different victim and this in/out parameter is used to convey its choice.

The callback function can use the iterator to iterate over all the transactions in the system. The iterator owns the transaction-list mutex, and if this function is not using that mutex, or if it invokes other static methods on xct_t, it must release the mutex by calling iter->never_mind().

The curr parameter indicates whte bytes of log consumed by the active transactions and the thresh parameter indicates the threshold that was just exceeded.

The logfile parameter is the name (including path) of the log file that contains the oldest log record (minimum lsn) needed to roll back any of the active transactions, so it is the first log file candidate for archiving.

If the server's policy is to abort a victim, it needs only set the victim parameter and return eUSERABORT. The storage manager will then abort that transaction, and the storage manager method that was called by the victim will return to the running thread with eUSERABORT.

If the server's policy is not to abort a victim, it can use xct_t::log_warn_disable() to prevent the callback function from being called with this same transaction as soon as it re-enters the storage manager.

If the policy is to archive the indicated log file, and an abort of some long-running transaction ensues, that log file might be needed again, in which case, a failure to open that log file will result in a call to the second callback function, indicated by the LOG_ARCHIVED_CALLBACK_FUNC pointer. If this function returns RCOK, the log manager will re-try opening the file before it chokes.

This is only a stub of an experimental handling of the problem. It does not yet provide any means of resetting the counters that cause the tripping of the LOG_WARN_CALLBACK_FUNC. Nor does it handle the problem well in the face of true physical media limits. For example, if, in recovery undo, it needs to restore archived log files, there is no automatic means of setting aside the tail-of-log files to make room for the older log files; and similarly, when undo is finished, it assumes that the already-opened log files are still around. If a callback function renames or unlinks a log file, because the log might have the files opened, the rename/unlink will not effect a removal of these files until the log is finished with them. Thus, these hooks are just a start in dealing with the problem. The system must be stopped and more disks added to enable the log size to increase, or a fully-designed log-archiving feature needs to be added. Nor is this well-tested.

The example log_exceed::cpp is a primitive example using these callbacks. That example shows how you must compile the module that uses the API for xct_t.


Classes

class  smthread_t
 Storage Manager thread. More...

Functions

static rc_t ss_m::setup_options (option_group_t *grp)
 Add storage manager options to the given options group.
 ss_m::ss_m (LOG_WARN_CALLBACK_FUNC warn=NULL, LOG_ARCHIVED_CALLBACK_FUNC get=NULL)
 Initialize the storage manager.
 ss_m::~ss_m ()
 Shut down the storage manager.
static void ss_m::set_shutdown_flag (bool clean)
 Cause the storage manager's shutting down do be done cleanly or to simulate a crash.

Function Documentation

static rc_t ss_m::setup_options ( option_group_t *  grp  )  [static, inherited]

Add storage manager options to the given options group.

Parameters:
[in] grp The caller's option group, to which the storage manager's options will be added for processing soon.
Before the ss_m constructor can be called, setup_options must be called. This will install the storage manager's options and initialize any that are not required. Once all required options have been set, an ss_m can be constructed.

Note:
This is not thread-safe. The application (server) must prevent concurrent calls to setup_options.
Examples:
create_rec.cpp, log_exceed.cpp, sort_stream.cpp, startstop.cpp, and vtable_example.cpp.

ss_m::ss_m ( LOG_WARN_CALLBACK_FUNC  warn = NULL,
LOG_ARCHIVED_CALLBACK_FUNC  get = NULL 
) [inherited]

Initialize the storage manager.

Parameters:
[in] warn A callback function. This is called when/if the log is in danger of becoming "too full".
[in] get A callback function. This is called when the storage manager needs an archived log file to be restored.
When an ss_m object is created, the storage manager initializes itself and, if the sthreads package has not already been initialized by virtue of an sthread_t running, the sthreads package is initialized now.

The log is read and recovery is performed ([MHLPS]), and control returns to the caller, after which time storage manager threads (instances of smthread_t) may be constructed and storage manager may be used.

The storage manager is used by invoking its static methods. You may use them as follows: 

 ss_m *UNIQ = new ss_m();

 W_DO(UNIQ->mount_dev(...))
     // or
 W_DO(ss_m::mount_dev(...))
).

Only one ss_m object may be extant at any time. If you try to create another while the one exists, a fatal error will occur (your program will choke with a message about your mistake).

The callback argument given to the storage manager constructor is called when the storage manager determines that it is in danger of running out of log space. Heuristics are used to guess when this is the case.

If the function warn archives and removes log files, the function get must be provided to restore those log files when the storage manager needs them.

For details and examples, see smlevel_0::LOG_WARN_CALLBACK_FUNC, smlevel_0::LOG_ARCHIVED_CALLBACK_FUNC, and Running Out of Log Space.

ss_m::~ss_m (  )  [inherited]

Shut down the storage manager.

When the storage manager object is deleted, it shuts down. Thereafter it is not usable until another ss_m object is constructed.

static void ss_m::set_shutdown_flag ( bool  clean  )  [static, inherited]

Cause the storage manager's shutting down do be done cleanly or to simulate a crash.

Parameters:
[in] clean True means shut down gracefully, false means simulate a crash.
When the storage manager's destructor is called the buffer pool is flushed to disk, unless this method is called with clean == false.

Note:
If this method is used, it must be called after the storage manager is constructed if it is to take effect. Each time the storage manager is constructed, the state associated with this is set to true, i.e., "shut down properly".

This method is not thread-safe, only one thread should use this at any time, presumably just before shutting down.

Generated on Wed Jul 7 17:22:34 2010 for Shore Storage Manager by  doxygen 1.4.7