Last modified: 11 May 2011
Name: H5Pset_elink_file_cache_size
Signature:
  herr_t `H5Pset_elink_file_cache_size`( hid_t `fapl_id`, unsigned `efc_size` )

Purpose:
  Sets the number of files that can be held open in an external link open file cache.

Motivation:
  The external link open file cache holds files open after they have been accessed via an external link. This cache reduces the number of times such files are opened when external links are accessed repeatedly and can siginificantly improves performance in certain heavy-use situations and when low-level file opens or closes are expensive.

  `H5Pset_elink_file_cache_size` sets the number of files that will be held open in an external link open file cache; `H5Pget_elink_file_cache_size` retrieves the size of an existing cache; and `H5Fclear_elink_file_cache` clears an existing cache without closing it.

Description:
  `H5Pset_elink_file_cache_size` specifies the number of files that will be held open in an external link open file cache.

  The default external link open file cache size is 0 (zero), meaning that files accessed via an external link are not held open. Setting the cache size to a positive integer turns on the cache; setting the size back to zero turns it off.

  With this property set, files are placed in the external link open file cache cache when they are opened via an external link. Files are then held open until either they are evicted from the cache or the parent file is closed. This property setting can improve performance when external links are repeatedly accessed.

  When the cache is full, files will be evicted using a least recently used (LRU) scheme; the file which has gone the longest time without being accessed through the parent file will be evicted and closed if nothing else is holding that file open.

  Files opened through external links inherit the parent file’s file access property list by default, and therefore inherit the parent file’s external link open file cache setting.

  When child files contain external links of their own, the caches can form a graph of cached external files. Closing the last external reference to such a graph will recursively close all files in the graph, even if cycles are present.

Parameters:

  hid_t `fapl_id` |  | IN: File access property list identifier
  unsigned `efc_size` |  | IN: External link open file cache size in number of files. Default setting is `0` (zero).

Returns:
  Returns a non-negative value if successful; otherwise returns a negative value.

Example Usage:
  The following code sets up an external link open file cache that will hold open up to 8 files reached through external links:

          status = H5Pset_elink_file_cache_size(fapl_id, 8);

See Also:

  `H5Pget_elink_file_cache_size` `H5Fclear_elink_file_cache` | `H5Lcreate_external` `H5Pset_elink_fapl`

History:

  Release | Change
  1.8.7 | C function introduced in this release.