Files

An SSlib file is an HDF5 file with a certain minimum internal structure: all SSlib files contain a group named “/SAF” which serves as the top-level scope for the file (there may be additional groups that also implement other scopes). The top-level scope is always opened with the file’s communicator and has a Scope table in addition to the usual tables. The Scope table is a list of all scopes contained in the file and the first element of that table is the top-level scope itself.

Every scope also has a File table that lists all files referred to by objects stored in that scope. The first element of every File table is understood to be the file containing that table.

Files are always opened with the ss_file_open function (or the convenience ss_file_create) and closed with ss_file_close. The file-related functions operate on or return a link of type ss_file_t, which points to some entry in a top-scope’s File table.

In addition to the collection of File tables in all scopes of all files that are currently open, the library maintains a per-task list of files and a mapping from the File table members to this global list. The mapping from a File table member to the gfile array is accomplished with the ss_file_open function. This allows the following:

• Members from multiple File tables can point to a common underlying HDF5 file,
• The file whose name was originally recorded in the File table can be temporarily renamed,
• Newly discovered file objects can be implicitly opened if they match a previous open file.

The implicit opening needs more discussion: whenever SSlib opens a file (call it the master file) it looks at the File tables of the master file to discover the names of all subordinate files that might be referenced by the master file (i.e., all ss_file_t objects except the first one in each table, which refers to the master file itself). If any of the subordinate names are relative, it temporarily converts them to absolute names using the master file’s directory as the current working directory and uses these converted names when searching for matching entries in the GFile array. If the subordinate file under consideration matches a name in the GFile array then the subordinate file will point to that entry, thus sharing the entry with some other file; otherwise the subordinate file will point to a brand new entry. In any case, the subordinate file’s explicit_open flag will be set to false and the GFile entry’s cur_opens counter will not be incremented. If the GFile entry is marked as currently open then the subordinate file is also implicitly open, sharing the same underlying HDF5 file and MPI communicator. Any implicitly opened file can be reopened at any time, either with the same flags as it already shares or with a brand new name, and once that happens the file is considered to be explicitly opened. Care should be taken to ensure that object links weren’t already dereferenced through the implicitly opened file, or two or more links that look identical might not be so (this could actually be checked by SSlib with an appropriate counter). Only files that are explicitly opened can be explicitly closed. Any implicitly opened files will implicitly close once all explicitly opened files in common are closed.

Members

• ss_file_open [Public function]
• ss_file_references [Public function]
• ss_file_openall [Public function]
• ss_file_create [Public function]
• ss_file_isopen [Public function]
• ss_file_istransient [Public function]
• ss_file_iswritable [Public function]
• ss_file_readonly [Public function]
• ss_file_synchronize [Public function]
• ss_file_synchronized [Public function]
• ss_file_flush [Public function]
• ss_file_close [Public function]
• ss_file_registry [Public function]
• ss_file_topscope [Public function]