PK_DELTA Functions

Contents

• C.1 Introduction
  • C.1.1 Example PK_DELTA frustrum code
  • C.1.2 Criteria of use
  • C.1.3 Registering the rollback frustrum functions
  • C.1.4 Delta functions that can be registered
    • C.3.1.5 open_for_write
    • C.3.1.6 open_for_read
    • C.3.1.7 close
    • C.3.1.8 write
    • C.3.1.9 read
    • C.3.1.10 delete

[back to top]

C.1 Introduction

This appendix contains the specifications of the Frustrum functions required for the PK partitioned rollback system.

Partitioned rollback requires six registered frustrum functions. Together these functions provide a virtual file system in which byte streams may be created or read. Byte streams are denoted by PK_DELTA_t values, not filenames, and are referred to as delta files. The delta value, which is positive, is assigned by the application Frustrum.

The partition rolling mechanism works by storing the changes between pmarks. These record the entities which need to be created, modified or deleted in order to move from one pmark to an adjacent one (either backwards or forwards). These deltas are written out through the Frustrum interface, stored by the application Frustrum, and read back in during a roll operation.

C.1.1 Example PK_DELTA frustrum code

The file frustrum_delta.c in the Parasolid release area lists the code for an example PK_DELTA Frustrum, required for running the partitioned PK rollback system.

The example Frustrum is provided for the following purposes:

• To allow the building and running of the Parasolid installation acceptance test program.
• To allow users to build and run simple prototype applications using rollback without first having to write a complete Frustrum.
• To aid users in writing their own Frustrum.

This Frustrum contains the bare minimum required to be used, in order for it to remain clear and platform independent. Normally a Frustrum is written with a particular application in mind, and may make use of system calls rather than the C run-time library for enhanced performance.

C.1.2 Criteria of use

• Delta files are not read beyond their length.
• Delta files deleted by Parasolid (via delete) are not referred to again.
• The Frustrum must only delete files when told to.
• There may be more than one delta file associated with a given pmark at a given time.
• If a new pmark is created, and the partition is currently at a pmark, a zero-length delta is output to the Frustrum, which must be stored.
• The pmark passed to the open_for_write function may sometimes be PK_PMARK_null, in which case the delta does not correspond to a pmark visible to the application. The application should store this delta as usual, and it is deleted by Parasolid when no longer required.

There is further information on the Frustrum requirements of Partitioned Rollback in Chapter 95, “Partitions”, of the Parasolid Functional Description Manual.

C.1.3 Registering the rollback frustrum functions

The partitioned rollback functions must be registered with Parasolid by calling the function PK_DELTA_register_callbacks, before the Parasolid session is started.

C.1.4 Delta functions that can be registered

This section describes the delta functions that you can register during a Parasolid session.

C.3.1.5 open_for_write

PK_ERROR_code_t open_for_write

(

PK_PMARK_t      pmark, /* pmark associated with delta */

PK_DELTA_t      delta  /* delta file to open          */

)

Opens a new delta file for writing, associated with the given pmark. Returns a PK_DELTA_t value chosen by the Frustrum which Parasolid uses to identify this delta file.

If pmark is PK_PMARK_null, the delta file is internal to Parasolid and is deleted when no longer required.

C.3.1.6 open_for_read

PK_ERROR_code_t open_for_read

(

PK_DELTA_t      delta /* delta file to open */

)

Opens an existing, closed delta file for reading.

C.3.1.7 close

PK_ERROR_code_t close

(

PK_DELTA_t      delta /* delta file to close */

)

Closes delta file delta , which is open. The function close is provided as a courtesy to the application and is invoked as early as possible.

C.3.1.8 write

PK_ERROR_code_t write

(

PK_DELTA_t      delta,   /* delta file to write      */

int             n_bytes, /* number of bytes to write */

char           *bytes    /* bytes to write           */

)

Writes n_bytes to the delta file delta (which is open) from the array bytes . n_bytes may often be as small as 20, so the application may wish to provide a buffering mechanism.

C.3.1.9 read

PK_ERROR_code_t read

(

PK_DELTA_t      delta,   /* delta file to read                 */

int             n_bytes, /* number of bytes to read            */

char           *bytes    /* array in which to store read bytes */

)

Reads n_bytes from the delta file delta (which is open) to the array bytes . n_bytes may often be as small as 20, so the application may wish to provide a buffering mechanism. Parasolid never requests more bytes (in total) than were written. Parasolid does not guarantee that the sequence of values of n_bytes resembles those given to write .

If bytes is NULL then no data should be written to the array, but the file position should be advanced.

C.3.1.10 delete

PK_ERROR_code_t delete

(

PK_DELTA_t      delta /* delta file to delete */

)

The function delete is used by Parasolid to indicate that the given delta (which exists and is closed) is not required again. Parasolid performs no further operations (including delete ) on delta .

[back to top]