PSPDFAnnotationProviderRefreshing

Tells the receiver to flush any annotation changes to its store.

Locking Considerations

This method is called inside a write block (see -performBlockForWritingAndWait:) before a change that requires a refresh (like rotating a page) is performed. Try to avoid additional locking when implementing this method to minimize the risk of introducing lock inversions.

Called when the annotation provider should refresh its annotations for pages at the specified index. This method is usually called when a property of the page needs to be changed, like in -[PSPDFDocumentProvider setRotation:forPageAtIndex:].

Locking Considerations

This method is called inside a write block (see -performBlockForWritingAndWait:) after a change that requires a refresh (like rotating a page) is performed. Try to avoid additional locking when implementing this method to minimize the risk of introducing lock inversions.

The sequence of events for a refresh is as follows:

1. -performBlockForWritingAndWait: is called.
2. The writeBlock() is entered. The next steps are all within the write block.
3. -prepareForRefresh is called on all providers conforming to this protocol.
4. The page property requiring a refresh is changed (e.g. The page rotation).
5. -refreshAnnotationsForPagesAtIndexes: is called on all providers.
6. The writeBlock completes and returns.

Called before -prepareForRefresh and -refreshAnnotationsForPagesAtIndexes:. This method is called to encapsulate a “prepare, change, and refresh” transaction You should acquire any required locks, and then call the writeBlock(). Once writeBlock returns, release the lock and return from the method.

If your annotation provider inherits from PSPDFContainerAnnotationProvider, please use its -performBlockForReading:, -performBlockForWriting: and -performBlockForWritingAndWait: methods to implement all your locking requirements, and do not override any of them. If you cannot inherit from PSPDFContainerAnnotationProvider, the easiest way to achieve correct behavior, is to use a single (recursive) lock for all synchronization purposes, and implement this method by acquiring that lock, calling the block, and then releasing the lock again.

As this lock has to be coordinated with other annotation providers, try to avoid additional locking within your implementations of -prepareForRefresh and -refreshAnnotationsForPagesAtIndexes: to minimize the risk of introducing lock inversions.