/** Library code general to all domains. * *

Android

* *

Code annotated @{@linkplain waymaker.gen.ThreadRestricted ThreadRestricted}("app main") is * restricted to the application’s {@linkplain ApplicationX#isMainThread() main thread} under the * Android runtime. Much of the library code for Android is likewise restricted, but with no * annotation or other indication.

* *

Automatic restoration by public access (AutoRestore-public)

* *

Automatic restoration of an open dialogue will throw IllegalAccessException if the declaring * subclass of DialogFragment is not public.

* *

ContentProviderClient thread safety (ContentProviderClient-TS)

* *

ContentProviderClient is thread restricted, but not restricted to the * application’s main thread in particular. An instance is safely accessible from any * single thread. “Note that you should ... create a new ContentProviderClient instance * for each thread that will be performing operations.”

* *

ContentResolver thread safety (ContentResolver-TS)

* *

ContentResolver is indirectly documented as thread safe. * “Unlike ContentResolver, the methods here [in ContentProviderClient] ... are not thread safe”.

* *

DocumentsContract thread safety (DocumentsContract-TS)

* *

DocumentsContract buildXUri() methods appear to be thread safe * judging by inspection of the source code. Likewise for its parsing methods * getX(Uri).

* *

HttpResponseCache thread safety (HttpResponseCache-TS)

* *

HttpResponseCache appears to be thread safe judging by inspection of its source code.

* *

Parcel reuse (ParcelReuse)

* *

Parcel.recycle * clears the parcel by parcel.freeBuffer, which unfortunately is private. * Otherwise it might be possible to reuse a parcel instead of making repeated calls to obtain/recycle. * Alternatively it might be possible to clear it for reuse by calling parcel.setDataSize(0), * but that method is too poorly documented to rely on.

* *

Parcel thread safety (Parcel-TS)

* *

Parcel.obtain and .recycle methods appear to be thread safe judging by inspection * of the source code.

* *

Resources thread safety (Resources-TS)

* *

Resources appears to be thread safe judging by inspection of its source code. It synchronizes * extensively by locking, and explains elaborately in a comment why certain members “are not protected * by a lock”.

* *

Thread synchronization by final freezing (FreezeSync)

* *

“A thread that can only see a reference to an object after that object has been completely initialized * is guaranteed to see the correctly initialized values for that object’s final fields … * [including] versions of any object or array referenced by those final fields * that are at least as up-to-date as the final fields are.” * (17.5) * That’s an attempt to summarize the ‘freeze’ rule for final fields * (17.5.1), * which is difficult to parse. See also * JMM and final field freeze.

* *

In other words, given a fully constructed and properly referenced instance, a read from one of * its final fields happens-after all initialization of values accessible through that field. * The initial values of a composite member such as an array or collection, for example, are guaranteed * visible to any reader who accesses it (however indirectly) through a final field.

* *

Thread synchronization by starting (StartSync)

* *

“A call to start() on a thread happens-before any actions in the started thread.” * (17.4.5) * Therefore when thread T1 starts thread T2, it thereby ensures that every previous * action of T1 is visible to all subsequent actions of T2.

* *

Thread synchronization by termination detecting (TermSync)

* *

“The final action in a thread T1 synchronizes-with any action in another * thread T2 that detects that T1 has terminated.” (Java language specification, * 17.4.4) * “T2 may accomplish this by calling T1.isAlive() or T1.join().” So T2 ensures that * every previous action of T1 happens-before the moment of detection and is * thereby visible to all subsequent actions of T2.

* *

“All actions in a thread happen-before any other thread successfully returns * from a join() on that thread.” * (17.4.5) *