Document Checkpointing

PSPDFKit automatically saves annotations at certain trigger events. This mechanism works well, however, there’s still the opportunity to lose data if the device restarts, runs out of battery, or if your application crashes before a save completes.

With Document Checkpointing, PSPDFKit offers a checkpointing mode that works in the background, offering an effective crash recovery mechanism to restore unsaved changes. This is an advanced feature and disabled by default, as it requires some configuration to work effectively.

PSPDFKit Instant stores annotations in a database and synchronizes with your PSPDFKit Server as soon as a connection is available, which greatly reduces the chances of data loss if the app terminates suddenly. No checkpointing or other custom setup is needed. Read more in our Instant Offline Support guide.

Understanding Document Checkpoints

A checkpoint contains all the unsaved data in the document. Let’s call this the “dirty” data. This data is temporary and persisted into the document when -[PSPDFDocument saveWithOptions:completionHandler:] is called. With Document Checkpoints, this dirty data can be continually saved to a separate checkpoint file, and in the event of a crash, be restored to the document.

PSPDFKit allows you to control when these checkpoints are saved. This is done by setting PSPDFDocumentCheckpointer.strategy on the checkpointer property available on each PSPDFDocument.

The following strategies are available:

• PSPDFDocumentCheckpointingStrategyManual: The checkpoint has to be saved manually by calling -[PSPDFDocumentCheckpointer saveCheckpointWithCompletionHandler:]. This is the default.
• PSPDFDocumentCheckpointingStrategyTimed: The checkpoint will be saved at a preset interval, as long as the document exists, and there are unsaved changes.
• PSPDFDocumentCheckpointingStrategyImmediate: The checkpointer reacts to changes made to the document, saving a checkpoint every time a change is made.

For most use cases, PSPDFDocumentCheckpointingStrategyImmediate is a good option and does not affect performance by any significant amount.

Loading A Saved Checkpoint

To load a previously saved checkpoint, you must use the appropriate initializer on PSPDFDocument:

• +[PSPDFDocument documentWithContent:loadCheckpointIfAvailable:]

and the corresponding -initWithContent:loadCheckpointIfAvailable method.

Passing in YES to the loadCheckpointIfAvailable parameter loads the checkpoint, if available. It is important to note that while the document will content any previously unsaved objects saved in the checkpoint, the loaded changes are not saved to the document. To do this, you must still call -[PSPDFDocument saveWithOptions:completionHandler:]. This will cause the data from the checkpoint file to be written into the document, after which the checkpoint will be deleted from disk by the PSPDFDocumentCheckpointer.

Additional Information

Supported Document Types

PSPDFDocuments that are backed by more than one provider are not supported by document checkpoints currently. Documents that are not backed by a file (NSData/custom data provider) work well checkpointing, as long as certain care is taken with regards to their UID. When enabling checkpointing on a document that uses a custom UID, one must be sure that the UID is unique to that document, since the PSPDFDocumentCheckpointer uses the UID as a part of the checkpoint’s file name. Opening multiple instances of a document with the same UID, and making changes to while they have checkpointing enabled is not supported and will result in undefined behaviour.

Checkpoint Location

The checkpoints are stored in subfolder in the device’s Library (more info) folder. You do not have to manage this manually since each PSPDFDocumentCheckpointer will always delete the document’s previous checkpoint before saving the new one. Additionally, the directory in which the checkpoints are stored is cleaned up by removing any checkpoints that are longer than a week old. The checkpoints are not shared between the main app executable and any of its app extensions, since the Library directory is unique to each of them. Therefore, if an extension crashes whilst a document has unsaved changes, those changes will not be recoverable from the app or another extension.

Performance

There are two things to consider with Document Checkpointing in terms of performance:

• Saving: Depending on the strategy, the PSPDFDocumentCheckpointer saves checkpoints to the location specified above on a low priority background queue. This should not affect your application’s performance in any meaningful way.
• Loading: When loading the checkpoints as specified above, the loading of a document may take a little longer than usual since that is when the document is parsed, but the initialisers of PSPDFDocument are not affected. Since PSPDFDocument only parses the document when it is actually required, you might see a small slowdown when accessing properties that require parsing.