Taking Snapshots
[API's]

Detailed Description

Before querying for modified objects, HotSync creates a snapshot and specifies a bottom cover for each DataStore to be synchronized in the current session. It then calls alp_hscm_open_snapshot() to define the snapshot of changes included in the sync; this call fixes the top cover for each DataStore included in the snapshot. Together the bottom and top covers define the set of changes included in the snapshot; any object with a pedigree that lies between the top and bottom covers for the relevant DataStore is said to be "included" in the snapshot. alp_hscm_open_snapshot() returns a snapshot handle that contains both the bottom and top covers for the DataStores included in the snapshot. This handle is then passed to alp_hscm_read_modified_objects_begin().

The use of a snapshot solves three basic problems:

  1. It ensures that no changes are lost. When alp_hscm_open_shapshot() is called, the Change Manager waits for any pending changes to complete then atomically ticks its global clock. Any local changes made before the tick are included in this sync. Any local changes made after the tick are included in the next sync (the pedigree for any change made after the tick contains the new clock value and thus does not fall under the top cover).
  2. It prevents dangling references in closed loopless reference topologies. This is also an artifact of ticking a global clock. To illustrate this, suppose that objects in DataStore D1 reference objects in DataStore D2, and further suppose that each DataStore has its own local clock. Now, suppose that during a sync the clock for D2 is incremented before a concurrent process adds a new object O2 to its DataStore. Then O2 is not included in the current sync snapshot. Now, if an object O1 that references O2 is added to D1 before its clock is ticked, then O1 is included in the sync, creating a dangling reference to O2. However, if D1 and D2 share a global clock, then its tick occurs either before or after the concurrent process adds O2 to D2. If before, then neither O2 nor O1 is included in the sync. If after, then O2 is included in the sync and a dangling reference can't occur.
  3. It avoids the transmission of dangling references. To illustrate this, suppose that a new object O1 in DataStore D1 references a new object O2 in DataStore D2 and further suppose that both new objects are initially included in a HotSync snapshot. By definition, if a concurrent process modifies O2 before HotSync can read it from D2, O2 is then excluded from the snapshot. Unfortunately now when HotSync reads O1 from the DataStore, it will transmit a dangling reference to O2. This is prevented by retaining all object versions included in any "open" snapshot. In particular, when a change is made to an object included in an open snapshot, it is implemented by creating a new, more recent version of the object while retaining the existing version. When the snapshot is closed, any "old" object versions are deleted, unless they're required for another open snapshot. So, in the previous example, HotSync reads the version of O2 that existed when the snapshot was opened and transmits it during the sync, thus avoiding the transmission of a dangling reference. Unnecessary object versions are purged when a snapshot is closed.

Concurrent synchronizations will not introduce dangling references as long as:

  1. There are no loops in the reference topology.
  2. Each engine is "nice", meaning it adds referenced objects before referencing objects and nulls references before deleting referenced objects. HotSync is guaranteed to be "nice".


Functions

alp_status_t alp_hscm_add_datastore_to_snapshot (AlpHsSnapshotHandle hSnapshot, _TCHAR *locURI, AlpHsPedigreePtr botCover)
 Add a datastore to the input snapshot.
alp_status_t alp_hscm_close_snapshot (AlpHsSnapshotHandle hSnapshot)
 Close the input snapshot.
alp_status_t alp_hscm_create_snapshot (AlpHsChangeMgrHandle hChgMgr, AlpHsSnapshotHandle *phSnapshot)
 Create a new snapshot.
alp_status_t alp_hscm_delete_snapshot_handle (AlpHsSnapshotHandle hSnapshot)
 Deletes the input snapshot.
alp_status_t alp_hscm_is_datastore_modified (AlpHsSnapshotHandle hSnapshot, const _TCHAR *locURI, bool *pIsModified)
 Returns true if any objects from the specified datastore are included in the input snapshot.
alp_status_t alp_hscm_open_snapshot (AlpHsSnapshotHandle hSnapshot)
 Open the input snapshot.
alp_status_t alp_hscm_query_snapshot_top (AlpHsSnapshotHandle hSnapshot, AlpHsPedigreePtr *pTopCover)
 Retreives the current datastore's top cover.
alp_status_t alp_hscm_query_snapshot_top_local (AlpHsSnapshotHandle hSnapshot, _TCHAR *locURI, AlpHsPedigreePtr *pTopCover)
 Retrieve's the specified datastore's top cover.

Function Documentation

alp_status_t alp_hscm_add_datastore_to_snapshot (  AlpHsSnapshotHandle  hSnapshot,
_TCHAR *  locURI,
AlpHsPedigreePtr  botCover
) 
 

Add a datastore to the input snapshot.

Parameters:
[in] hSnapshot The Snapshot handle.
[in] locURI The datastore's locURI.
[in] botCover A coverage pedigree.
Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.
Remarks:
Objects in the specified datastore with pedigrees less than the specified botCover will not be included in the snapshot. When the botCover does not contain any clocks, all objects from the specified datastore will be included in the snapshot.
See also:
alp_hscm_create_snapshot(), alp_hscm_open_snapshot().

alp_status_t alp_hscm_close_snapshot (  AlpHsSnapshotHandle  hSnapshot  ) 
 

Close the input snapshot.

Parameters:
[in] hSnapshot The snapshot handle
Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.
See also:
alp_hscm_open_snapshot().

alp_status_t alp_hscm_create_snapshot (  AlpHsChangeMgrHandle  hChgMgr,
AlpHsSnapshotHandle *  phSnapshot
) 
 

Create a new snapshot.

Parameters:
[in] hChgMgr The ChangeMgr handle
[out] phSnapshot Pointer to a snapshot handle.
Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.
See also:
alp_hscm_add_datastore_to_snapshot(), alp_hscm_open_shapshot().

alp_status_t alp_hscm_delete_snapshot_handle (  AlpHsSnapshotHandle  hSnapshot  ) 
 

Deletes the input snapshot.

(OPTIONAL) Detailed description of function.

Parameters:
[in] hSnapshot The snapshot handle
Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.
See also:
alp_hscm_create_snapshot().

alp_status_t alp_hscm_is_datastore_modified (  AlpHsSnapshotHandle  hSnapshot,
const _TCHAR *  locURI,
bool *  pIsModified
) 
 

Returns true if any objects from the specified datastore are included in the input snapshot.

Parameters:
[in] hSnapshot Handle for an open snapshot
[in] locURI The datastore's locURI
[out] pIsModified The return value
Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.
Remarks:
When *pIsModified is true, modified objects from the specified datastore can be retrieved from the snapshot by using the read modified objects API.
See also:
alp_hscm_add_datastore_to_snapshot(), alp_hscm_read_modified_objects_begin().

alp_status_t alp_hscm_open_snapshot (  AlpHsSnapshotHandle  hSnapshot  ) 
 

Open the input snapshot.

This function determines the object versions included in the input snapshot. For each datastore in the snapshot, the objects included in the snapshot have pedigrees that are:

  1. Not less than or equal to the botCover specified when the datastore was added to the snapshot.
  2. Less than or equal to the datastore's current change coverage. The snapshot's top cover is set to the datastore's current coverage. The entire operation is performed atomically to prevent modifications to the datastore while the snapshot is being taken.

Parameters:
[in] hSnapshot The snapshot handle
Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.
See also:
alp_hscm_create_snapshot(), alp_hscm_add_datastore_to_snapshot().

alp_status_t alp_hscm_query_snapshot_top (  AlpHsSnapshotHandle  hSnapshot,
AlpHsPedigreePtr *  pTopCover
) 
 

Retreives the current datastore's top cover.

This function retrieves the top cover for the current datastore from the input snapshot. In this case the current datastore is defined as the datastore that was open when the snapshot was created.

Parameters:
[in] hSnapshot Handle for an open snapshot handle
[out] pTopCover Pointer to a pedigree pointer
Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.
Remarks:
The caller is responsible for free-in the output pedigree by passing it to alp_hs_pedigree_delete().
See also:
alp_hscm_create_snapshot(), alp_hscm_open_snapshot(), alp_hscm_query_snapshot_top_local(), alp_hscm_close_snapshot().

alp_status_t alp_hscm_query_snapshot_top_local (  AlpHsSnapshotHandle  hSnapshot,
_TCHAR *  locURI,
AlpHsPedigreePtr *  pTopCover
) 
 

Retrieve's the specified datastore's top cover.

This function retrieves the top cover for the specified datastore from the input snapshot.

Parameters:
[in] hSnapshot Handle for an open snapshot
[in] locURI The datastore's locURI
[out] pTopCover Pointer to a pedigree pointer
Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.
Remarks:
The caller is responsible for free-in the output pedigree by passing it to alp_hs_pedigree_delete().
See also:
alp_hscm_create_snapshot(), alp_hscm_open_snapshot(), alp_hscm_query_snapshot_top().

Generated on Wed Jul 30 07:06:41 2008 by Doxygen 1.4.6 for ALP SDK + Hiker Documentation

Copyright © 1999-2008 ACCESS CO., LTD. All rights reserved.