9. Managing Repository Space

Repository Growth

Repository extents not only have to hold the data in your database, they also need to hold the changes all the users make, and coordinate the views of each user so the user has a consistent snapshot view of the data. All these activities require space in the extents.

The repository begins in the compact form of $GEMSTONE/data/extent0.dbf. As repository activity progresses, the extent file expands as more space is needed, in increments of 16 MB. Not only does your new application data require space, but space is required for internal structures that organize and manage the objects. Also, sessions, and their transactional views of the repository, require space.

Garbage objects—objects that are no longer referenced, or the older versions of objects— also use space in the repository until they are garbage collected. To manage the size of the extents, you need to regularly perform garbage collection on your GemStone repository. The frequency can vary from monthly to daily, depending on the amount of activity in the repository. Without garbage collection, the repository will continue to grow and be filled with wasted space. See Chapter 15, “Managing Repository Growth”, for a discussion of garbage collection in GemStone.

How To Check Free Space

Use the methods Repository>>fileSize and Repository>>freeSpace to obtain reports about the logical repository as a whole.

The result of the message fileSize is the total size of the repository in bytes, including all extent files. If the repository consists of a single extent file, it is ordinarily the same result as you would obtain by using the operating system commands to find file size. For example:

topaz 1> printit

SystemRepository fileSize

%

153092096

The result of freeSpace tells how much space (in bytes) is available for allocation within the repository at its current size. Free space is equal to the sum (for all extents in the repository) of the number of free pages in each extent multiplied by the page size. This space does not include fragments on partially filled data pages.

topaz 1> printit

SystemRepository freeSpace

%

26411008

Depending on the configuration options selected and the available disk space, the Stone repository monitor may be able to create additional free space by enlarging the repository.

If your configuration has more than one extent, use Repository>>fileSizeReport to generate statistics about each individual extent and also totals for the entire repository. (The heading “Extent #1” identifies the primary extent regardless of its file name, which by default is extent0.dbf.)

topaz 1> printit

SystemRepository fileSizeReport

%

Extent #1

  Filename = /users/extents/extent0.dbf

  File size =       256 MB

  Space available =  34 MB

-----------

Extent #2

  Filename = /users/extents/extent1.dbf

  File size =        64 MB

  Space available =   9 MB

------

Totals

  Repository size = 320 MB

  Free Space =       43 MB

To Add an Extent While the Stone is Running

To prevent the repository from becoming full, you can dynamically add another extent to the Stone configuration. This section describes the Smalltalk methods that allow you to do this.

For general information about multiple extents, see Configuring the Repository Extents.

topaz 1> run

SystemRepository createExtent: '$GEMSTONE/data/extent2.dbf'

%

#  DBF_EXTENT_NAMES written by Stone (user gsadmin) on 8/04/23 12:56:18 PDT

DBF_EXTENT_NAMES = "$GEMSTONE/data/extent0.dbf",

"$GEMSTONE/data/extent1.dbf",

"!@::1#dbf!/gshost/GemStone3.7/data/extent2.dbf";

To Remove an Extent

The only way to remove an extent file is by first performing a Smalltalk full backup and restore to move the contents of that extent to other extents.

Privileges required: FileControl.

Reducing the number of existing extents requires special steps to ensure data integrity. If you must remove an extent file, follow this procedure:

Step 1. Back up your repository using the Smalltalk full backup procedure described under How To Make a Smalltalk Full Backup.

You cannot use an online or offline extent backup to remove or shrink extents (obviously).

Step 2. Shut down the Stone repository monitor.

Step 3. Modify the DBF_EXTENT_NAMES configuration option to show the new extent structure.

Step 4. Restore the repository from your Smalltalk full backup. Follow the GemStone restore procedure described under Restoring from a Full Backup.

To Reallocate Objects Among a Different Number of Extents

If you are increasing or decreasing the number of extents and want to change allocation of existing objects as part of that operation, perform a Smalltalk full backup, then restore the backup after setting appropriate weights for DBF_ALLOCATION_MODE.

For example, suppose your existing repository contains 800 MB and you want to divide them about equally between the existing extent and a new one. To populate each extent with about 400 MB, follow this procedure:

Step 1. Back up your repository, using the Smalltalk full backup procedure described under How To Make a Smalltalk Full Backup. You cannot use an online or offline extent backup to redistribute objects (obviously).

Step 2. Shut down the Stone repository monitor.

Step 3. Modify the DBF_EXTENT_NAMES configuration parameter to show the new extent structure.

DBF_EXTENT_NAMES = $GEMSTONE/data/extent0.dbf,$GEMSTONE/data/extent1.dbf;

Step 4. Edit DBF_ALLOCATION_MODE to reflect the intended distribution of pages (see Allocating Data to Multiple Extents). For example:

DBF_ALLOCATION_MODE = 10, 10;

Step 5. Restore the repository from your Smalltalk full backup, using the procedure described under Restoring from a Full Backup.

If objects in the repository were explicitly clustered using instances of ClusterBucket that explicitly specified the first extent, those objects may tend to migrate back to that extent over time. You can prevent such migration by placing size limits on the existing extent, or by explicitly reclustering those objects in the new extent using a ClusterBucket that specifies either an extentId of nil or the extentId of the new extent. For information about clustering, refer to the Programming Guide.

To Reallocate Objects Among the Same Number of Extents

Changes to DBF_ALLOCATION_MODE directly affect only the subsequent allocation of pages for new or modified objects. When you restore into a repository with the same number of extents, the distribution of the original repository will be used in the restored repository, regardless of the DBF_ALLOCATION_MODE.

To change the allocation of existing objects, you can either restore into a repository with a different number of extents (as discussed in the previous section) or you can specify a temporary maximum size on the extent files during the restore, to force objects to be distributed as you want them.

For example, suppose your existing repository has three extents, and that you are running in sequential allocation mode. The first extent has 600 MB, while the second and third extents are 4 MB each (the minimum size). You now want to redistribute the objects so they are spread evenly over all three extents. You cannot simply change the DBF_ALLOCATION_MODE, and restore a backup into three extents; existing objects would be distributed according to the original allocation mode, that is, entirely in the first extent. Only new objects created after the restore would be created evenly over the three extents.

To populate the three extents evenly, you can follow this procedure:

Step 1. Back up your repository, using the Smalltalk full backup procedure described under How To Make a Smalltalk Full Backup.

Step 2. Shut down the Stone repository monitor.

Step 3. Edit the DBF_EXTENT_SIZES configuration option to limit the size of the first extent temporarily to 200 MB. For example:

DBF_EXTENT_SIZES = 200MB, , ;

Step 4. Edit the DBF_ALLOCATION_MODE configuration option to reflect the intended distribution of pages (see Allocating Data to Multiple Extents). This setting determines the distribution of new or modified objects. For example:

DBF_ALLOCATION_MODE = 10, 10, 10;

Step 5. Restore the repository from your Smalltalk full backup, using the procedure described under Restoring from a Full Backup.

Step 6. If you want the first extent to grow beyond the temporary limit you set in Step 3, stop the Stone after you restore the repository. Edit the configuration file again, either specifying a higher limit or no limit. For example:

DBF_EXTENT_SIZES = , ,  ;

If objects in the repository were explicitly clustered using instances of ClusterBucket that explicitly specified the first extent, those objects may tend to migrate back to that extent over time. You can prevent such migration by maintaining the size limit set in Step 3, or by explicitly reclustering those objects in the new extent using a ClusterBucket that specifies either an extentId of nil or the extentId of the new extent. For information, refer to the Programming Guide.

Handling signals indicating a commit record backlog

Even in manual transaction mode, it is possible to cause a commit record backlog, depending on how your system is configured. Sessions should ensure that they commit or abort regularly, or set up sigAbort handlers to abort when requested by the Stone. A sigAbort handler may be as simple as this:

Exception 

   installStaticException: 

   [ :exception :GSdictionary :errID :array |

      System abortTransaction.

      System enableSignaledAbortError).

Exception 

   installStaticException: 

   [ :exception :GSdictionary :errID :array |

      System continueTransaction.

      System enableSignaledFinishTransactionError).

Repository full

The Stone takes a number of actions to prevent the repository from becoming completely full. If the free space remaining in the repository falls below the level set by the STN_FREE_SPACE_THRESHOLD configuration option and the Stone cannot allocate more space in any extent, it takes the following actions to prevent a system crash:

1. It becomes more aggressive about disposing of commit records so that garbage collection can proceed. (If the Stone is very busy, a backlog of commit records can accumulate.)

2. It starts a checkpoint if there isn't one in progress and reduces the checkpoint interval to three minutes until the condition clears. (This checkpoint may free pages that have been reclaimed.)

3. It writes a message to the Stone log to indicate the condition.

4. It prevents new logins except for DataCurator and SystemUser accounts. It issues a disk-full error to other sessions attempting to log in.

5. It signals the Exception RepositoryError to any sessions logged in (or logging in) as DataCurator or SystemUser so that they know disk space is becoming critical.

6. It signals Gem session processes to return all except five free pages per extent. It responds to requests for additional pages by allocating only five pages at a time.

7. If the free space available drops below 400 KB (50 pages), the Stone stops responding to page requests from sessions that are not logged in as DataCurator or SystemUser. This action prevents users from acquiring all of the available space, which would cause the system to crash. Gem session processes appear to “hang” while they are waiting for pages. The unhonored page requests are granted when the free space goes back above the threshold.

8. If the previous steps do not solve the problem within the time specified by the STN_DISKFULL_TERMINATION_INTERVAL configuration option, then the Stone begins to terminate sessions holding on to the oldest commit record even if the session is in a transaction. This action applies to any user session, including logins as SystemUser and DataCurator. Allowing the Stone to dispose of the commit record allows additional garbage collection.

NOTE
You can configure the Stone to never terminate sessions by setting STN_DISKFULL_TERMINATION_INTERVAL to 0; however, doing so increases the risk of GemStone shutting down because of a lack of free space in the repository.

9. When the condition clears, another message is written to the Stone log and operation returns to normal.

If you see a message like the following while logged in as DataCurator or SystemUser or in the Stone log, disk space is becoming critical:

The repository is currently running below the freeSpaceThreshold.

When the system must dynamically expand the repository, it checks one extent at a time, in the order dictated by the allocation strategy, to see if that extent can be expanded to create more space. When no extents can be extended and the free space is below STN_FREE_SPACE_THRESHOLD, the Stone takes the actions described above.

Failure to expand an extent has two possible causes: either the disk containing the extent is full, or the extent has reached its maximum size as set by the DBF_EXTENT_SIZES configuration option.

There are a number of things you can do to create more space in an existing extent, or you can create a new extent. Each of these actions may create sufficient additional space for immediate needs:

• Warn the current users about the problem, and have them log out until enough space is made available.
• Remove any non-essential files to create enough space for expanding the repository.
• Create a new extent through Smalltalk with Repository>>createExtent: or a related method. If the Stone has stopped, you can create a new extent by editing the parameters in the configuration file before restarting it. See Adding and Removing Extents.

Keyfile limits reached

Some GemStone licencing terms place a limit on the maximum size of a repository, which is limited by the keyfile. When a repository with a keyfile limit on repository size reaches that size limit, the Stone will shut down due to out of space. However, with a licence limit, is not possible to simply add extents or disk space to allow GemStone to restart. You must contact GemTalk Technical Support for a temporary keyfile with an increased limit, so you can restart GemStone and take whatever steps are necessary to make space available.

If the keyfile has a size limit, it is important to avoid your repository’s size reaching the licence limit. It is strongly recommended that you do not set a repository size (in which case the limit will be computed as 80% of the licence limit), or if you do, set the limit to 80% of your keyfile limit.