Initialize the library¶
saf_init
is a macro defined in SAFinit.h.
Synopsis:
-
saf_init
(PROPERTIES)¶
Description: The saf_init
function must be called by the client to initialize the client’s interaction with the library
and should be called before any other SAF-API function except functions that set the properties to be passed
in the saf_init
call.
Calling saf_init
when the library is initialized has absolutely no effect, even when a new, different list
of properties is specified.
The counterpart of saf_init
is saf_final, which releases all resources held by the library. The saf_init
function must be called after saf_final if the client desires to interact with the library again.
Since all SAF clients are required to call saf_init
, we’ve chosen to wrap that
function in a macro which also makes a reference to a global variable whose name is derived from the SAF
version number. This variable is declared in the SAF library so that if an application is compiled with SAF
header files which have a different version than the SAF library a link-time error will result. A version
mismatch will result in an error similar to undefined reference to ``SAF__version_1_4_0`’ from the linker.
Return Value: The constant SAF__SUCCESS
is returned for success; errors are returned as other values or by exception,
depending on the setting of the error handling property in PROPERTIES
(the default is to return an error number).
Parallel Notes: In parallel, saf_init
is collective and must be called by all processes in the library’s communicator, which
is MPI_COMM_WORLD
by default. All processes must initialize the library with the same property values,
although each may pass its own PROPERTIES
argument.
If a new communicator is specified in the PROPERTIES
argument then it will become the communicator for any
database which doesn’t override this communicator. It is the maximal communicator in the sense that no
database can be opened on a set of processors which is not a subset of those in the communicator declared in
the properties passed here.
Issues: Verify that the set of processors which must participate in this call is either MPI_COMM_WORLD
or the
communicator passed in the PROPERTIES
.
We might want to communicate to confirm that all procs pass the same properties.
See the private function, _saf_init
, for the real implementation of this function
Calling saf_init
after saf_final is currently not supported.
See Also:
- saf_final: 4.2: Finalize access to the library
- Library Initialization: Introduction for current chapter