Lock a PDF document in Android

An Apryse SDK lock is based on two principles:

Reentrant mutex (also known as recursive lock)
Recursive mutex may be locked multiple times by the same process/thread without causing a deadlock.

Readers-writer (RW) lock (also known as shared-exclusive lock)
An RW lock allows concurrent access for read-only operations, while write operations require exclusive access.

To write to a PDF document in a multithreaded environment.

1PDFDoc doc = new PDFDoc(filename);
2
3// Lock the document
4doc.lock();
5
6// ... perform some document processing using write operations
7
8// Now we release the lock
9doc.unlock();

1val doc = PDFDoc(filename)
2
3// Lock the document
4doc.lock()
5
6// ... perform some document processing using write operations
7
8// Now we release the lock
9doc.unlock()

Multithreaded PDF reading
Full source code which illustrates how to use PDFDoc locking mechanisms to access the document concurrently. PDFDoc uses a recursive shared lock model.

To read and write to a PDF document in a multithreaded environment.

1PDFDoc doc = new PDFDoc(filename);
2
3// Lock the document
4doc.lock();
5
6// Optionally note that locking a second time does not cause a deadlock
7doc.lock();
8
9// You can acquire a read lock while holding a write lock:
10doc.lockRead();
11
12// ... perform some document processing using read operations
13
14doc.unlockRead();
15
16// ... perform some document processing using write operations
17
18// Releasing the lock decrements our lock count,
19// but the thread still holds a write lock on the document
20doc.unlock();
21
22// Now we release the write lock, and
23// other tasks can begin execution
24doc.unlock();

1val doc = PDFDoc(filename)
2
3// Lock the document
4doc.lock()
5
6// Optionally note that locking a second time does not cause a deadlock
7doc.lock()
8
9// You can acquire a read lock while holding a write lock:
10doc.lockRead()
11
12// ... perform some document processing using read operations
13
14doc.unlockRead()
15
16// ... perform some document processing using write operations
17
18// Releasing the lock decrements our lock count,
19// but the thread still holds a write lock on the document
20doc.unlock()
21
22// Now we release the write lock, and
23// other tasks can begin execution
24doc.unlock()

Multithreaded PDF reading
Full source code which illustrates how to use PDFDoc locking mechanisms to access the document concurrently. PDFDoc uses a recursive shared lock model.

As computing devices become more parallel in nature, Apryse is evolving to allow developers to leverage this power in new and exciting ways. Apryse version 6.0 introduces new locking semantics which allow for concurrent access of a PDFDoc instance. This was done to improve performance during interactive viewing (simultaneous rendering, text extraction, etc.), as well as to open up the possibility for new use cases (parallel rendering). This article introduces the locking system, and will get you on your way to developing parallel applications with Apryse SDK.

Apryse uses a recursive read/write locking system. Multiple threads can hold a read lock on the document, but only one thread can hold a write lock at any given time. A thread can acquire an equivalent or weaker lock as many times as it likes without causing a deadlock. In other words, the following is valid:

1PDFDoc d = new PDFDoc("foo.pdf");
2d.lock();
3d.lock();
4d.lockRead();

1val d = PDFDoc("foo.pdf")
2d.lock()
3d.lock()
4d.lockRead()

However, a thread cannot acquire a write lock while holding a read lock. Because one can only acquire a write lock when no read locks are held, this situation would inevitably lead to a deadlock. To avoid this scenario, Apryse will throw a runtime exception whenever the situation occurs.

Some of our API calls internally acquire a write lock on the document. As a result, these calls can also throw a runtime exception if they are invoked while holding a read lock. This is noted in each method's documentation. Additionally, you will find a complete list of those methods at the end of this article.

In general, the parts of our library that manage the UI will maintain document locks. For the lower level calls which actually modify the document, you are responsible for maintaining document locks.

Apryse provides the following APIs for locking the document:

1void PDFDoc.lock()
2boolean PDFDoc.tryLock(int milliseconds)
3void PDFDoc.unlock()
4void PDFDoc.lockRead()
5boolean PDFDoc.tryLockRead(int milliseconds)
6void PDFDoc.unlockRead()

1fun PDFDoc.lock()
2fun PDFDoc.tryLock(milliseconds: Int) : Boolean
3fun PDFDoc.unlock()
4fun PDFDoc.lockRead()
5fun PDFDoc.tryLockRead(milliseconds: Int) : Boolean
6fun PDFDoc.unlockRead()

The new locking system is backwards compatible, meaning previous calls to PDFDoc.Lock now acquire a write lock. If you would like to take advantage of the ability to read a PDF concurrently, it is your responsibility to review document locks and determine whether it is safe to downgrade them to a read lock.

Conversely, if you are happy with the existing 'one document, one thread' model previously used in Apryse 5.9., you can continue to work with this system. No change is required on your behalf.

For convenience, PDFView or PDFViewCtrl exposes similar methods, which will be applied to the currently open document or associated document. Additionally, the PDFView.DocLock or PDFViewCtrl.DocLock method takes a cancel_rendering parameter, which will interrupt all worker threads currently accessing the document. This allows you to acquire the write lock as fast as possible:

1void PDFViewCtrl.docLock(boolean cancel_rendering)
2boolean PDFViewCtrl.docTryLock(int milliseconds)
3void PDFViewCtrl.docUnlock()
4void PDFViewCtrl.docLockRead()
5boolean PDFViewCtrl.docTryLockRead(int milliseconds)
6void PDFViewCtrl.docUnlockRead()

1fun PDFViewCtrl.docLock(cancel_rendering : Boolean)
2fun PDFViewCtrl.docTryLock(milliseconds: Int) : Boolean
3fun PDFViewCtrl.docUnlock()
4fun PDFViewCtrl.docLockRead()
5fun PDFViewCtrl.docTryLockRead(milliseconds: Int) : Boolean
6fun PDFViewCtrl.docUnlockRead()

At the low level, a PDFDoc uses an input filter to access its PDF data. this data could be stored on the file system, in a memory buffer, or over a network. Now that Apryse supports concurrent access of PDFDoc across many threads; these input filters must also be made thread-safe. StdFile, which was not a thread-safe filter, is no longer available. Instead, you should now use the new MappedFile filter, which provides thread-safe and efficient read access on a file. Custom user filters are still supported, although they are now wrapped in an internal filter that guarantees thread safety.

1void PDFViewCtrl.closeDoc()
2void PDFViewCtrl.setDoc(PDFDoc)

1fun PDFViewCtrl.closeDoc()
2fun PDFViewCtrl.setDoc(pdfdoc: PDFDoc)