PSPDFAnnotationProviderRefreshing

@protocol PSPDFAnnotationProviderRefreshing <PSPDFAnnotationProvider>

Protocol to be implemented by any annotation provider that allows refreshing of its annotations in response to an external change, like from -[PSPDFDocumentProvider setRotation:forPageAtIndex:].

  • 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.

    Declaration

    Objective-C

    - (void)prepareForRefresh;

    Swift

    func prepareForRefresh()
  • 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:) 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.

    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. -refresAnnotationsForPagesAtIndexes: is called on all providers.
    6. The writeBlock completes and returns.

    Declaration

    Objective-C

    - (void)refreshAnnotationsForPagesAtIndexes:(nonnull NSIndexSet *)pageIndexes;

    Swift

    func refreshAnnotationsForPages(at pageIndexes: IndexSet)

    Parameters

    pageIndexes

    An NSIndexSet containing indexes of the pages that should be refreshed.

  • 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 PSPDFAnnotationProvider, the easiest way to achieve correct behavior, is to use a single (recursive) lock for all its 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.

    Note

    It is important that this be synchronous.

    Declaration

    Objective-C

    - (void)performBlockForWritingAndWait:(nonnull void (^)(void))writeBlock;

    Swift

    func performBlock(forWritingAndWait writeBlock: @escaping () -> Void)

    Parameters

    writeBlock

    The block that should be called when the locks are acquired.