PK_THREAD_lock_partitions

PK_ERROR_code_t                      PK_THREAD_lock_partitions
(
--- received arguments ---
int                                  n_partitions,          --- (> 0)
const PK_PARTITION_t                 partitions[],
PK_THREAD_lock_t                     lock_type,
PK_THREAD_wait_t                     wait_type,
const PK_THREAD_lock_partitions_o_t *options,

--- returned arguments ---
PK_THREAD_lock_partitions_r_t *const results
)


This function attempts to lock partitions to the calling thread, i.e. make
partitions (and items within them) only usable in this thread.


Specific Errors:
    PK_ERROR_rollback_not_started   Partitioned rollback is not active (MILD)
    PK_ERROR_bad_partition          Partition is current (MILD)
    PK_ERROR_not_at_pmark           Partition is not at a pmark (MILD)
    PK_ERROR_bad_mark               Partition is at its initial pmark (MILD)
    PK_ERROR_locked                 Thread already has partitions locked (MILD)
    PK_ERROR_not_stopped            Thread is in a chain (MILD)
    PK_ERROR_recursion_depth        Called within an outer PK or KI function
                                    (MILD)
    PK_ERROR_bb_not_empty           Bulletin board is not empty (MILD)


Partitions to lock to the calling thread are specified using the 'partitions'
array, together with the value of 'lock_type':
  o If set to PK_THREAD_lock_all_c, this function will attempt to lock all
    the specified 'partitions'.
  o If set to PK_THREAD_lock_one_c, this function will attempt to lock
    only the first, currently available, partition in 'partitions', i.e. the
    first partition that is not locked and no other threads are waiting to
    lock.

If some partitions are currently unavailable, i.e. already locked or other
threads are waiting to lock them, then the behaviour of this function depends
on the value of 'wait_type':
  o If set to PK_THREAD_wait_yes_c, this function will queue fairly until
    other threads have signalled that all the partitions to lock have become
    available.
  o If set to PK_THREAD_wait_no_c, this function will immediately return.

The output of this function is returned in the 'results' structure:
  o If the 'status' field is set to PK_lock_status_ok_c, only the partitions
    this function locked (and items within them) are usable in the calling
    thread until PK_THREAD_unlock_partitions is next called. The first locked
    partition in 'partitions' becomes the current partition for this thread.
  o If the 'status' field is set to PK_lock_status_fail_c, no partitions
    will be locked to the calling thread.
  o All the partitions that this function locked can be optionally returned
    in the 'locked_partitions' field.
  o All the partitions that are currently unavailable can be optionally
    returned in the 'unavailable_partitions' field.

While a thread has locked partitions:
  o PK functions with local exclusivity will run concurrently in the thread.
  o The following session settings will maintain thread-specific values:
    PK_SESSION_set_behaviour
    PK_SESSION_set_check_continuity
    PK_SESSION_set_check_self_int
    PK_SESSION_set_close_knots
    PK_SESSION_set_general_topology
    PK_SESSION_set_mesh_angle
    PK_SESSION_set_rebuild_history
    PK_SESSION_set_roll_forward
    PK_SESSION_set_software_option
    PK_SESSION_set_swept_spun_surfs
  o Any further partitions that it creates or receives will automatically be
    locked to it.
  o Any pre-existing session marks are unusable in the thread and cannot be
    rolled to in any thread.

These PK functions (and their KI equivalents) cannot be used while partitions
are locked to any thread:
    PK_SESSION_receive
    PK_SESSION_receive_u
    PK_SESSION_set_facet_geometry
    PK_SESSION_transmit
    PK_SESSION_transmit_u

This function should only be called when partitioned rollback has been started
with PK_DELTA_register_callbacks.