33.2 Examining and Adjusting MVFS Cache Size

Client hosts that use dynamic views may be able to benefit from MVFS cache tuning. Use the getcache command to print information about your MVFS cache. For example:

cleartool getcache -mvfs
Mnodes: (active/max) 1791/8192 (21.863%)
Mnode freelist: 1701/1800 (94.500%)
Cltxt freelist: 737/1800 (40.944%)

DNC: Files: 848/1600 (53.000%)
Directories: 185/400 (46.250%)
ENOENT: 827/1600 (51.688%)

RPC handles: 4/10 (40.000%)

NOTE: The statistics presented above are in the form current-number-on-list/list-capacity and (percentage-of-list-capacity).

Attribute cache miss summary (for tuning suggestions, see the
documentation for administering ClearCase):
Attribute cache total misses: 49609 (100.00%)
Close-to-open (view pvt) misses: 18964 ( 38.23%)
Generation (parallel build) misses: 1179 ( 2.38%)
Cache timeout misses: 234 ( 0.47%)
Cache fill (new file) misses: 0 ( 0.00%)
Event time (vob/view mod) misses: 29232 ( 58.92%)

You may want to change ClearCase MVFS cache sizes to improve performance, if your host performs builds that involve a large (greater than 400) number of files.

Remember, the size of physical memory is the key factor, but caching changes may help.

To resize the MVFS caches, do one of the following:

• Use cleartool setcache -mvfs to test different MVFS cache sizes. This method allows you to evaluate results before making a permanent change. See Real-Time Updating of MVFS Cache Sizes for details.

• On a UNIX host, set the mvfs_largeinit option. This affects a number of other default sizing values and is the preferred method for making a long-lived change. For details, see Adjusting the MVFS Memory Initialization Factor.

• On a Windows host, increase the scaling factor on the MVFS Performance tab in the ClearCase program in Control Panel. This raises a number of default sizing values and is the preferred method for a long-lived change. See the online help for the MVFS Performance tab as well as Adjusting the MVFS Memory Initialization Factor for more details.

• Override selected values for some or all of the specific caching components. (See Setting Individual Caching Parameters on UNIX.) This method provides somewhat finer control, but the suggested values are generally close to those used by mvfs_largeinit. On Windows computers, this value is represented in the ClearCase Control Panel as the scaling factor on the MVFS Performance tab.

NOTE: On some UNIX computers, you must recompile the kernel after changing mvfs_largeinit. For details, see the Platform-Specific Guide in online help.

Increasing mvfs_largeinit adds about 500 KB to the size of kernel (200 KB nonpageable, 300 KB pageable) memory for each increment of the mvfs_largeinit value or scaling factor. Enlarging the MVFS caches reduces the amount of memory available to applications but provides better performance when the working set of objects in a build or command exceeds the default cache allocations. Increase the value gradually and check the cache utilization with cleartool getcache -mvfs. If you change your MVFS configuration, also consider reconfiguring each view that is used to access ClearCase data on that host, increasing its view_server cache size. See Reconfiguring a View.

Table 12 describes each tunable caching parameter with recommendations for setting its size. Also shown is the relationship among the fields in the getcache output, the setcache options, and the names of the caching parameters.

Real-Time Updating of MVFS Cache Sizes

To perform real-time updating of the MVFS cache sizes, use cleartool setcache -mvfs, which modifies cache sizes without requiring you to shut down and restart your computer. Real-time updating is useful for testing different configurations until you find the one that is best for you.

• On UNIX computers, these changes are not persistent until you edit the values for each significant caching component as described in Setting Individual Caching Parameters on UNIX.

• On Windows computers, these changes are not persistent until you update the values on the MVFS Performance tab of the ClearCase Control Panel, and then shut down and restart your computer.

The entries in the sample output show the corresponding setcache options that can be used to make adjustments to these caches.

cleartool getcache -mvfs
Mnodes: (active/max) 1791/8192 (21.863%) (grows automatically)
Mnode freelist: 1701/1800 (94.500%) (adjust with -vobfree option)
Cltxt freelist: 737/1800 (40.944%) (adjust with -cvpfree option)

DNC: Files: 848/1600 (53.000%) (adjust with -regdnc option)
Directories: 185/400 (46.250%) (adjust with -dirdnc option)
ENOENT: 827/1600 (51.688%) (adjust with -noentdnc option)

RPC handles: 4/10 (40.000%) (adjust with -rpchandles option)
.
.
.

You probably also need to use the mvfsstat and mvfstime commands to determine the effectiveness of your cache before manipulating its size. A full cache is not necessarily ineffective if its hit rate is high enough. We recommend maintaining a hit rate of 85% or better.

NOTE: setcache can sometimes fail with a "Device busy" error. Such errors are usually transient and indicate that some other process is also trying to use the MVFS.

Adjusting the MVFS Memory Initialization Factor

You can specify how much memory the MVFS uses for various caches by changing the MVFS scaling factor.

The MVFS scaling factor is set automatically, as shown in Table 13, based on the amount of physical memory installed in the host computer.

Table 13 How Memory Size Affects the MVFS Scaling Factor

Memory Size	<24MB	24MB-256MB	256MB-1GB	>1GB
MVFS Scaling Factor	0	1	2	size/512MB +1

If you wish, you can manually override the automatic setting.

• On UNIX platforms, the scaling factor is the value of mvfs_largeinit. The way in which mvfs_largeinit is set is platform specific. The Platform-Specific Guide, in online help, has more information about platform-specific values for mvfs_largeinit. For greater control over your cache sizes, you can set the individual caching parameters as described in Setting Individual Caching Parameters on UNIX.

• On Windows platforms, the scaling factor is set to 1 by default. To change the scaling factor, start the ClearCase Control Panel. On the MVFS Performance tab, set the scaling factor value in the Scaling factor to initialize MVFS with more memory for better performance box. Click OK. Changes take effect after you shut down and restart your computer. For finer control over the individual cache sizes, you can change some of the individual values. See Setting Individual Cache Sizes on Windows.

Changing the value of mvfs_largeinit or the Scaling Factor scales all of the MVFS cache sizes proportionally as shown in Table 14.

Table 14 How the MVFS Scaling Factor or mvfs_largeinit Affects Individual MVFS Cache Sizes

MVFS Cache Name	scaling factor or mvfs_largeinit = 0	scaling factor or mvfs_largeinit = 1	scaling factor or mvfs_largeinit = 2	scaling factor or mvfs_largeinit > 0
DNC File Cache	800 bytes	1600 bytes	2400 bytes	800(N+1) bytes
DNC Directory Cache	200 bytes	400 bytes	600 bytes	200(N+1) bytes
DNC ENOENT Cache	800	1600	2400	800(N+1)
Cleartext File Cache (UNIX)	900	1800	2700	900(N+1)
Cleartext File Cache (Windows)	900	1800	1800	1800
RPC Handle Cache	5	10	15	5(N+1)
Mnode Freelist Cache	900	1800	2700	900(N+1)
Mnode Cache	4096	8192	1288	4096(N+1),N<4; 2048(N+7),N>4

Setting Individual Caching Parameters on UNIX

Platform-specific instructions for changing caching parameters on all supported UNIX systems are provided in the Platform-Specific Guide in online help.

The following list identifies all significant caching components and provides the default values as loaded at system startup. You can bypass this level of detail by choosing the mvfs_largeinit option as described in Adjusting the MVFS Memory Initialization Factor.

• Cache for the systemwide maximum number of mnodes is set with the mvfs_mnmax parameter at up to 4,096 MVFS objects. The cache grows dynamically if more is required.

• The maximum number of unused mnodes to cache (at 400 bytes/object) is set with the mvfs_vobfreemax parameter, which has a default value of 900.

• The minimum number of unused mnodes to keep on the VOB free list set with the mvfs_vobfreemin parameter. This parameter has a default value of 0, which causes mvfs_vobfreemin to be set at 90% of mvfs_vobfreemax.

• The maximum number of unused cleartext files to cache differs by system. The value is set by mvfs_cvpfreemax. The Platform-Specific Guide provides detailed information.

• Caches for MVFS directory name objects are set with these parameters:

• The number of regular file names to cache (at 100 bytes/entry) is set by mvfs_dncregmax.

• The number of directory names to cache (at 100 bytes/entry) is set by mvfs_dncdirmax.

• The number of names that produce name-not-found returns (at 100 bytes/entry) is set by mvfs_dncnoentmax.

The default value for each of these parameters is 0, which causes the size of the cache to be determined by the value of mvfs_largeinit.

For the individual cache sizes associated with particular values of mvfs_largeinit, see Adjusting the MVFS Memory Initialization Factor.

Setting Individual Cache Sizes on Windows

Use the ClearCase Control Panel to modify individual cache sizes. On the MVFS Performance tab, select the Override check box for a particular value. Enter a new value for the parameter. When you have finished modifying fields, click OK.

Each mnode in the mnode freelist cache uses about 400 bytes. Each entry in the DNC files, directories, and ENOENT caches uses about 100 bytes.

After changing cache sizes, you must shut down and restart your computer to make your changes take effect.

Minimizing Attribute Cache Misses

The sections that follow this sample output describe each cache-miss category and the ways to reduce the miss count.

cleartool getcache -mvfs
.
.
.
Attribute cache miss summary (for tuning suggestions, see the
documentation for administering ClearCase):
Attribute cache total misses: 49609 (100.00%)
Close-to-open (view pvt) misses: 18964 ( 38.23%)
Generation (parallel build) misses: 1179 ( 2.38%)
Cache timeout misses: 234 ( 0.47%)
Cache fill (new file) misses: 0 ( 0.00%)
Event time (vob/view mod) misses: 29232 ( 58.92%)

Attribute Cache Total Misses

Total misses is the sum of all the misses entries. This total is reduced by reducing the other categories of misses entries described below.

Close-to-Open Misses

Close-to-open misses occur when an open view-private file is reopened by another process. The MVFS rechecks with the view_server when a view-private file is reopened to refresh its cached attributes in case the file was modified by another MVFS client.

This behavior can be disabled on a per-computer (not a per-view) basis. If you are absolutely sure that no other client on the network is updating view-private files in any views you are using from an MVFS client, you may want to disable this behavior to reduce these cache misses.

Use mvfscache to change this setting.

Generation Misses

Generation misses occur during a parallel build. If you are doing parallel builds, you cannot avoid these misses.

Cache Timeout Misses

Cache timeout misses occur when a file's attributes have not been verified recently. The MVFS periodically rechecks a file's attributes to ensure that it does not cache stale copies of the attributes.

These misses cannot be completely eliminated. However, the time-out period for the attributes may be adjusted. The cache timeout varies, depending on how recently a file or directory was modified; the more recently the file was modified, the shorter the time-out period. The value for this initial time-out period is constrained to lie within the minimum and maximum attribute-cache lifetimes as specified at VOB mount time through the acregmin/acregmax (for regular files) and acdirmin/acdirmax (for directories) parameters. These are the default values:

• acregmin: 3 seconds

• acregmax: 60 seconds

• acdirmin: 30 seconds

• acdirmax: 60 seconds

If you consider changing these values, be aware that a longer timeout means that this client may not notice other clients' updates to the VOB or view for longer periods.

To change these values, specify a mount option for the VOB in one of the following ways:

• At mount time. For example:

cleartool mount -options acregmin=30 vob-tag

This is a privileged operation. You must be the privileged user to do this.

• In the registry (either at VOB creation with mkvob or later using mktag). For example:

cleartool mktag -vob -tag vob-tag -replace -options mount-options ...

NOTE: The time-out values specified in these mount options affect the view's metadata latency (the delay before changes to VOB metadata become visible in a dynamic view other than the one in which the changes were made). Longer time-out values improve performance at the expense of greater latency. Shorter time out values decrease latency, but also have an impact on view performance because the caches must be refreshed more frequently.

Cache Fill Misses

Cache fill misses occur when a file's attributes are not in the cache. If the percentage of these is high (above 20%), your cache may be too small for your working set. Consider increasing the number of mnodes on the free list by changing the mvfs_vobfreemax parameter as described in Setting Individual Caching Parameters on UNIX and Setting Individual Cache Sizes on Windows.

Event Time Misses

Event time misses occur when a cached name-to-object translation requires revalidation of the attributes on the resulting object (for example, the name cache has "foo" mapped to a particular file object, but the attribute cache on that object needs to be refreshed because of a timeout or a parallel-build-induced generation miss).

These misses cannot be completely eliminated, but as with Cache Timeout Misses they can be reduced by adjusting minimum/maximum cache lifetimes.