Collaboration diagram for Starting Up, Shutting Down, Thread Context:
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 create_rec::cpp 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.
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.
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.
|Storage Manager thread. More...|
|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. |
|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. |
Add storage manager options to the given options group.
|[in]||grp||The caller's option group, to which the storage manager's options will be added for processing soon.|
|ss_m::ss_m||(||LOG_WARN_CALLBACK_FUNC|| warn =
|LOG_ARCHIVED_CALLBACK_FUNC|| get = |
Initialize the storage manager.
|[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.|
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:
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.
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||)||
Cause the storage manager's shutting down do be done cleanly or to simulate a crash.
|[in]||clean||True means shut down gracefully, false means simulate a crash.|
This method is not thread-safe, only one thread should use this at any time, presumably just before shutting down.