Abstract: This document searches for improvements in threading model of the openide.text module under issue 33165.
It focuses purely on threading and various functionality descriptions, terminology etc. may be somewhat inaccurate.

Table of Contents

1 Problem

2 Threading Requirements

3 Changes Description

4 Conclusion

1. Problem

Current threading of openide.text does not use Document.render() to read-lock the document during document-related operations.
Because of that number of threading problems may arise. Issue 33040 is likely the most noticeable and unpleasant one.

2. Threading Requirements

Functionality Overview

Main functionality building blocks of the openide.text include

1. Creation of empty Swing document for a particular fileobject (dataobject)
2. Loading of contents of the fileobject into that empty document
3. Closing of the existing document
4. Automatic reloading of the document in case an external modification of the related fileobject occurs.
5. Conversion of position refs to/from memory kind once a document is loaded/closed.

Main Methods Overview

• CloneableEditorSupport.getDocument() - returns valid document instance if the document was loaded. Returns null if none has asked to open the document yet or if the document was closed previously. In case the document is being loaded it waits till the loading is finished and returns the loaded instance.
  The original reference in EditorCookie claimed that getDocument() does *no* waiting but certain issues arised with this approach which resulted in the current implementation that actually does wait in case the document is being loaded.
  Kinds of all PositionRef instances in the related position manager will be updated once the loading is finished.
• CloneableEditorSupport.openDocument() - get document instance and wait until it's loaded and then return it.

Requirements Possibly Affecting Locking

• Document related operations must be read-locked on the document by using Document.render().
  This is the main requirement why this whole effort is being done.
  No document locking which is the current state causes threading issues and exceptions being thrown from the document implementation.
• The added Read-locking of the document should be done prior to further locking in the scope of the openide.text.

  There is already a use case of the code first locking the document atomically by NbDocument.runAtomic() and manipulating the positions inside the executed Runnable. To avoid deadlocks caused by counter locking the added read-locking must be done prior to synchronization of PositionRef.Manager.

• Methods like getDocument() or openDocument() should have a clearer synchronization model.
  In the current state both getDocument() and openDocument() have certain initial portions of code unsynchronized.

  Note: Making changes related to this was not planned originally.
  I was forced to do them because after I have performed the read-locking changes certain threading issues started to occur. Concretely once I have created a java class in a wizard from a template with some methods overriden then in certain amount of cases (usually at least once from 10 invocations) I've got the java source file garbled. The overriden methods were generated in the middle of the javadoc for constructor.
  Originally I thought that my changes were the cause of the problem but later I"ve found out that the same errorneous behavior can be achieved by putting a debugging System.out.println() at certain place in PositionRef without doing any other changes.
  Still I was not convinced whether the openide.text is the culprit or whether the problem is somewhere else (e.g. in inproper synchronization of java metadata updating in java module) but after I've made the modifications to openide.text these problems went away.

3. Changes Description

• Methods accessing the document operations (e.g. accessing the paragraph elements or offset of a position) were wrapped into Runnables being executed through Document.render().
  If there are additional locks performed over read-locked document such as synchronization on PositionRef.Manager this is done *after* the read-lock on document is done.

  Note: To avoid creation of many anonymous inner classes there is just one DocumentRenderer inner class having several different constructors and opCode to determine the purpose it was constructed for.
  Although it works fine the code is not too nice to read. We can either live with that or we could possibly in the future require all the document implementations being used to extend AbstractDocument (e.g. all swing document implementations do so) where there are readLock() and readUnlock() public methods.

• Methods accessing the document in CloneableEditorSupport were modified to operate under CloneableEditorSupport.getLock().
  If the document is being loaded the threads will wait by using Object.wait() mechanism until loading of the document is finished.

4. Conclusion

There are still architectural issues to think about. For example in the existing openide.text design if someone calls openDocument() and e.g. write-locks the returned document instance and then starts to modify it then it should also attach the change listener to the CloneableEditorSupport to be notified that the document being changed was closed by another thread and that it is no longer valid. In case the notification comes the work done in the document should be abandoned and likely redone in the new document.
Otherwise it may happen that the modifications are done to the document no longer being valid.
The problem is that the notification about closing of the document can currently come anytime so theoretically the document could be closed but more importantly saved with just partial changes (because of the notifyModify() gets called during closing).
We could try to improve the situation by running the closeDocument() under write-lock on the document being closed. However to prevent deadlocks we should first write-lock the document obtained by previous call to getDocument() and then use CES.getLock() and do the document closing.
Even with that it's still possible that the document is closed between the moment when thread obtains the document instance by openDocument() and the moment when thread write-locks the document for modification.
However to fix this case we could set a property in the document once it closed e.g. doc.putProperty("closed", Boolean.TRUE). The property would only have to be checked once right after the write-lock (or read-lock) was obtained on the document returned from openDocument().