setcache

Changes cache settings

Applicability

Product Command type

VersionVault

cleartool subcommand

Platform

UNIX

Linux

Windows

Synopsis

  • Specify the cache size for a single view:
    setcache -vie/w { -def/ault | -cac/hesize size }
    { -cvi/ew | view-tag }
  • Specify the cache size for a host:
    setcache -vie/w -hos/t { -def/ault | -cac/hesize size }
  • Specify the sitewide view cache size:
    setcache -vie/w -sit/e { -def/ault | -cac/hesize size }
    [ -pas/sword registry-password ]
  • VersionVault dynamic views--Specify MVFS cache sizes:
    setcache -mvfs [-zone zone_name] [-per/sistent | -persistent_only ]
    { -reg/dnc cnt | -noe/ntdnc cnt | -dir/dnc cnt | -vob/freemax cnt

    | -cvp/freemax cnt | -rpc/handles cnt | -vobfreemin cnt

    | -cvpfreemin cnt | -mnmax cnt

    | { -cto | -ncto } | { -aca/che | -nac/ache }

    | { -dnc/ache | -ndnc/ache }

    | { -rdr/ache | -nrdr/ache }

    | { -rvc/ache | -nrvc/ache } } ...

  • VersionVault dynamic views--Specify MVFS scaling factor or readdir cache sizes and make persistent:
    setcache -mvfs [-zone zone_name] { -per/sistent | -persistent_only }
    {-rea/ddir_blocks cnt | -scalefactor val } ...
  • VersionVault dynamic views--Reset MVFS cache sizes to default values and make persistent:
    setcache -mvfs [-zone zone_name] { -per/sistent | -persistent_only } -def/ault
  • VersionVault dynamic views--Specify the number of Solaris zones that are expected to run the MVFS:
    setcache -mvfs -expected_zone_count cnt

Description

The setcache command sets MVFS and view cache sizes. Although both dynamic and snapshot views use caches, cache size is more significant for a dynamic view than for a snapshot view.

VersionVault--View caches

The dynamic view caches consist mostly of data retrieved from the VOB and enable the view_server to respond faster to RPCs from client machines. When a view_server process is started, it chooses its cache size from the first of the following sources to yield a value:

  • The dynamic view's cache size, which is set with mkview -cachesize or setcache -view -cachesize and stored in the file view-storage-dir/.view (on the -cache line)
  • The view_server host's default cache size, which is set with setcache -view -host and stored as a decimal number in the file /var/adm/hcl/versionvault/config/view_cache_size (UNIX and Linux) or versionvault-home-dir\var\config\view_cache_size (Windows)
  • The site-wide cache default, which is set with setcache -view -site or setsite and stored in the site config registry
  • The default value: 4096 KB.
Note: If your view uses the host value or the site-wide value and that value is changed, your view's cache size does not change until you invoke setcache -view -default or restart the view_server (with endview -server or a reboot).

The dynamic view cache size is allocated among the individual caches. When specifying a cache size, keep the following guidelines in mind:

  • The value cannot be smaller than 512 KB.
  • Do not specify a value larger than the amount of physical memory on the server host that you want to dedicate to this view.
  • Verify your changes by using getcache to check the hit rates and utilization percentages periodically to see whether they have improved.

VersionVault dynamic views--MVFS caches

A host's MVFS caches are used to optimize file system performance:

  • The directory name cache accelerates name translation. This cache is partitioned into three areas, each of which can be tuned with one of the setcache -mvfs options:
    • Directory files (-dirdnc)
    • Nondirectory files (-regdnc)
    • Names not found (ENOENT) (-noentdnc)
      Note: If processes are actively using the directory name cache, you may see the following error message when trying to resize it:

      cleartool: Error: Unable to set some current MVFS parameters
      to requested values because caches are in active use.

      Ask users to stop using VersionVault actively (that is, keep their view contexts, but stop manipulating files) and enter the setcache command again.

  • The attribute cache accelerates access to file metadata (for example, by the stat and access system calls, which are frequently called during make or clearmake operations). The -vobfreemax and -vobfreemin options establish the high- and low-water marks for the attribute cache for VOB and view-private files that are not currently open; the -mnmax option sets this value for both opened and unopened files.
  • The cleartext cache accelerates the open system call for files in a VOB and view-private files. The -cvpfreemax and -cvpfreemin options establish the high- and low-water marks for this cache. This cache is never larger than the size of the attribute cache.
  • The RPC handles cache accelerates RPCs to the dynamic view. The -rpchandles option sets the size of this cache; the value ought to be the maximum simultaneous number of RPCs expected from your host. If this value is too small, the getcache -mvfs command recommends that you adjust its size.
When the MVFS is started, it chooses its cache size from the first of the following sources to yield a value:
  • Values set by a previous setcache -persistent or setcache -persistent_only.
  • The default cache size established when VersionVault was installed on the host.
  • The default value. On the UNIX system and Linux, this is a per-host value based on the size of the host's physical memory. On Windows, the site-wide default is used, regardless of system memory size.

For more information about using setcache, see the discussion of client performance tuning in the Help.

Restrictions

Identities

  • UNIX and Linux:
    • For setcache -view, you must be root on the view_server host or the view owner.
    • For setcache -view -host, and setcache -mvfs -zone, you must be root.
    • For setcache -mvfs -expected_zone_count, you must be root on the Solaris global zone.
  • Windows:
    • For setcache -view, you must be the view owner.
    • For setcache -view -host, you must have create/delete/write permissions on the file versionvault-home-dir\var\config\view_cache_size.
    • For setcache -mvfs, you must be local administrator or a member of the Administrators group.
  • For setcache -view -site, you must know the registry password

Locks

No locks apply.

Mastership

(Replicated VOBs) No mastership restrictions.

Options and arguments

Specifying the cache information to change

Default
None.
-vie/w
Sets the cache size for a single view. This immediately changes the cache size; you do not need to kill and restart the view_server.
-vie/w -hos/t
Sets the default cache size for the current host.
-vie/w -sit/e
Sets the site-wide default size for view caches.
-mvfs
Sets cache sizes for the MVFS, either temporarily or persistently.
-zone
Specifies the MVFS cache size for a nonglobal zone on Oracle Solaris systems running on SPARC and x86 computers. For more information on using this option, see the administrator help topics. For general information on nonglobal zones, refer to Oracle documentation.
-expected_zone_count cnt
Specifies the number of Solaris zones (global, non-global, branded) that are expected to run the MVFS.

The recommended value is the total number of zones (global and non-global) that are expected to run HCL VersionVault on that computer. VersionVault uses this value to compute the scaling factor and cache sizes for the MVFS. Specifically, the total available memory on the system is divided by the number of expected zones, and then algorithms are applied to set the scaling factor and cache sizes. If the expected number of zones is not specified, the scaling factor in the global zone is computed based on the total system memory size, and the scaling factor in the other zones is set to one by default. With an unspecified number of zones, the appropriate cache sizes for the MVFS might not be allocated equitably across zones, which can result in non-optimal performance.

Setting the cache size

Default
None.
-def/ault
With -view, removes the -cache line from the .view file. This immediately sets the size of the view cache to (in priority order) the host size, the site-wide size, or the default size. (SeeDescription.)

With -view -host, deletes the /var/adm/hcl/versionvault/config/view_cache_size (UNIX and Linux) or versionvault-home-dir\var\config\view_cache_size (Windows) file.

With -view -site, removes the value for the site-wide cache from the registry.

When used with setcache -mvfs, -default must be used with the -persistent or -persistent_only option, and restores MVFS cache values to installed defaults. (See Description.) Setting certain values that force changes in other values may cause setcache to print a message explaining that the new values will not take effect until you restart the MVFS.

-cac/hesize size
Specifies a size for the view_server cache. size must be an integer value of bytes, optionally followed by the letter k to specify kilobytes or m to specify megabytes; for example, 800k or 3m.

Specifying the view

Default
None.
-cvi/ew
Sets the cache size for the current view.
view-tag
Specifies the view for which the cache size is changed.

Specifying the registry password

Default
When you set the sitewide view cache size with -view -site, setcache prompts you for the registry password.
-pas/sword registry-password
Specifies the sitewide registry password.

Specifying MVFS parameters (not applicable to snapshot views)

Default
None. You must specify at least one option. cnt and val must be integer values. For information about default and suggested values, see the Help. Setting certain values that force changes in other values may cause setcache to print a message explaining that the new values will not take effect until you restart the MVFS.
-per/sistent
When this option is specified with the options -readdir_blocks or -scalefactor, then the options are set persistently, but are not effective until the MVFS is restarted. In other words, in the contexts of -readdir_blocks or -scalefactor, this option is identical to -persistent_only.

In all other cases, this option specifies that all options are applied immediately and also set persistently. If you do not specify -persistent, options revert to their former values when the MVFS is restarted.

-persistent_only
Specifies that all options will be set persistently but will not take effect until the MVFS is restarted.

NOTE: This option is not supported for Solaris nonglobal zones.

-reg/dnc cnt
Sets the number of regular file DNC entries.
-noe/ntdnc cnt
Sets the number of ENOENT (file not found) DNC entries.
-dir/dnc cnt
Sets the number of directory DNC entries.
-vob/freemax cnt
Sets the maximum number of free (unused) attribute cache entries. This is a subset of the total specified by -mnmax.
-cvp/freemax cnt
Sets the number of entries in the cleartext cache.
-rpc/handles cnt
Sets the number of RPC handles cached by the MVFS.
-vobfreemin cnt
Sets the minimum number of mnodes to keep on the VOB free list.
-cvpfreemin cnt
Sets the minimum number of mnodes to keep on the cleartext free list.
-rea/ddir_blocks cnt
Sets the number of blocks cached for each directory read by the MVFS. Valid only with -persistent or -persistent_only.
-mnmax cnt
Sets the initial number of mnodes cached by the MVFS. (Several internal values are derived from this value, but will not be changed until after the MVFS is restarted.)
-sca/lefactor val
Sets the scaling factor used to initialize the MVFS with more memory for better performance. Valid only with -persistent or -persistent_only.
-cto
Enables close-to-open consistency checking.
-ncto
Disables close-to-open consistency checking.
-aca/che
Enables attribute caching.
-nac/ache
Disables attribute caching.
-dnc/ache
Enables directory name caching.
-ndnc/ache
Disables directory name caching.
-rlc/ache
Enables readlink caching.
-nrlc/ache
Disables readlink caching.
-rdrc/ache
Enables the read-directory cache, which accelerates the reading of directory entries.
-nrdrc/ache
Disables the read-directory cache.
-rvc/ache
Enables root version caching.
-nrvc/ache
Disables root version caching.

Examples

The UNIX system and Linux examples in this section are written for use in csh. If you use another shell, you might need to use different quoting and escaping conventions.

The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you might need to change the wildcards and quoting to make your command interpreter process the command appropriately.

In cleartool single-command mode, cmd-context represents the UNIX system and Linux shells or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.

  • Change the cache size for view smg_test.

    cmd-context  setcache -view -cachesize 800k smg_test
    The new view server cache limits are:
    Lookup cache:                   78624 bytes
    Readdir cache:                 327680 bytes
    File stats cache:              137592 bytes
    Object cache:                  275184 bytes
    Total cache size:            819200 bytes

  • Set the site-wide cache size.

    cmd-context  setcache -view -site -cachesize 2m
    Registry password: <enter registry password><ENTER>
    ...

  • Set the MVFS scaling factor to 3 (dynamic views).

    cmd-context  setcache -mvfs -persistent -scalefactor 3