Create a new persistent object¶
ss_pers_new
is a function defined in sspers.c.
Synopsis:
-
ss_pers_t *
ss_pers_new
(ss_scope_t *scope, unsigned tableid, const ss_persobj_t *init, unsigned flags, ss_pers_t *buf, ss_prop_t UNUSED *props)¶
Formal Arguments:
scope
: The scope that will own this new object.tableid
: A magic number whose sequence part defines a tableinit
: Optional initial data of typess_persobj_t
or a type derived therefrom. The type must be appropriate for the class of object being created. This argument can be used to copy a persistent object.ISSUE
: Should this be a link instead?flags
: Creation flags, like SS_ALLSAMEbuf
: Optional buffer for return valueprops
: Additional properties (none defined yet)
Description: Creates a new persistent object of the specified object type in the specified scope. Normally this function
assumes that every caller could be creating its own object and the table synchronization algorithm will
determine later how many objects were actually created by comparing their contents. However, synchronization
can be an expensive operation which can be avoided when the caller knows that all tasks of the scope’s
communicator are participating to create a single object. This is situation is noted by passing the
SS_ALLSAME bit in the flags
argument.
Return Value: Returns a link to the new object on success; the null pointer on failure. If buf
is supplied then that will be
the successful return value, otherwise a persistent object link will be allocated.
Parallel Notes: Independent or collective. This function must be collective across the scope’s communicator (although
communication-free) if the SS_ALLSAME bit is passed in the flags
argument. In other words, if all
tasks are participating to create one single object, then the call must be collective if we wish to avoid the
synchronization costs later. However, it is still possible for all tasks to create one single object
independently (i.e., creation order doesn’t matter) if they don’t pass SS_ALLSAME and they don’t
mind paying the synchronization cost later.
See Also:
- ss_pers_copy: 7.2: Copy an object
- Persistent Objects: Introduction for current chapter