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 table
  • init: Optional initial data of type ss_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_ALLSAME
  • buf: Optional buffer for return value
  • props: 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: