Managing ObjectStore

osgc: Garbage Collection Utility

 Garbage collection frees storage associated with persistent objects that are unreachable. Applications can continue to use a database while garbage collection is in process.

The command-line utility for collecting garbage is osgc. Invoke this tool with the following format:

Syntax

osgc [ options ] database_name

Options
-seg segment_id
Collects garbage from only the specified segment. By default, the osgc utility operates on the entire database. 

-retries number
Indicates the number of times the tool tries to resume the sweep phase of garbage collection after it waits for a lock. The default is 10.

 
-retryInterval interval
Indicates the number of milliseconds the sweep operation waits between sweep attempts for a concurrency conflict to be resolved before it tries to resume the sweep. The default is 1000.

 
-lockTimeOut interval
Indicates the number of milliseconds the sweep operation waits for a lock conflict to be resolved. If it is not resolved in the specified length of time, the tool aborts the current transaction and starts a new transaction. ObjectStore rounds this value up to the nearest second. The default is 1000. 

-transactionPriority n
Specifies the transaction priority associated with transactions started by the tool. The Server uses this specification when it must determine the transaction that must be the victim in a deadlock. This number is intentionally low so that the garbage collection transaction is the deadlock victim of choice. The default is 0. 

-displayGarbage level
Displays information about the candidates for garbage collection instead of actually destroying the candidates. The level you specify determines the amount of information the tool displays. 1 lists the number of objects per segment that would be destroyed. 2 is not currently supported. 3 lists the location of each garbage collector candidate. 4 lists the roots of garbage graphs. Level 4 can require intensive computations. 

-statistics
Displays statistics for the garbage collection operation. This includes the total number of reachable objects and the total number of garbage objects.

Performing Garbage Collection in a Database

 The ObjectStore persistent garbage collector (GC) collects unreferenced objects and ObjectStore collections in an ObjectStore database.

Persistent garbage collection frees storage associated with objects that are unreachable. It does not move remaining objects to coalesce the free space. (See oscompact: Compacting Databases.)

The GC performs its job in two major phases. In the mark phase, the GC identifies the unreachable objects. In the sweep phase, the GC frees the storage used by the unreachable objects.

A segment is the smallest storage unit that can be garbage collected. You can specify a segment or a database to be garbage collected.

C++ usage note

Normally, databases resulting from ObjectStore applications written in C++ do not require garbage collection because all storage allocation is handled explicitly.

osgc can be useful as a debugging tool. For example, if unreferenced objects are being harvested, it is an indication of a persistent memory leak. The identity of these objects can be a clue to the root of the problem.

Restriction

If your application relies on intersegment or interdatabase pointers, you should use segments and databases with the segment reference policy of objectore::export_id_access_required. Otherwise, references to one database from another will not be detected by osgc and objects pointed to by references from other databases will be seen as unreferenced and, therefore, removed.

Applications can continue to use a database while persistent GC is in progress. GC locks portions of a segment as needed, as if it were just another application. In this way, the GC minimizes the number of pages that are locked and the duration for which the locks are held. Also, the GC retries operations when it detects lock conflicts.

By default, the GC runs with a transaction priority of zero. Consequently, it is the preferred victim when the Server must terminate a transaction to resolve a deadlock. At a later time, the GC redoes the work that was lost when the transaction was aborted.

The GC uses read- and write-lock timeouts of short duration. This avoids competition with other processes for locks. If the GC cannot acquire a lock because of a timeout, it retries the operation at a later time.



[previous] [next]

Copyright © 1999 Object Design, Inc. All rights reserved.

Updated: 03/11/99 11:19:07