/** Library code general to all domains. * * <h3>Android</h3> * * <p>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.</p> * * <h3 id='AutoRestore-public'>Automatic restoration by public access (AutoRestore-public)</h3> * * <p>Automatic restoration of an open dialogue will throw IllegalAccessException if the declaring * subclass of DialogFragment is not public.</p> * * <h3 id='ContentProviderClient-TS'>ContentProviderClient thread safety (ContentProviderClient-TS)</h3> * * <p><a href='http://developer.android.com/reference/android/content/ContentProviderClient.html' * target='_top'>ContentProviderClient</a> 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.”</p> * * <h3 id='ContentResolver-TS'>ContentResolver thread safety (ContentResolver-TS)</h3> * * <p><a href='http://developer.android.com/reference/android/content/ContentResolver.html' * target='_top'>ContentResolver</a> is indirectly documented as thread safe. * “Unlike ContentResolver, the methods here [in <a href= * 'http://developer.android.com/reference/android/content/ContentProviderClient.html' * target='_top'>ContentProviderClient</a>] ... are not thread safe”.</p> * * <h3 id='DocumentsContract-TS'>DocumentsContract thread safety (DocumentsContract-TS)</h3> * * <p><a href='http://developer.android.com/reference/android/provider/DocumentsContract.html' * target='_top'>DocumentsContract</a> build<var>X</var>Uri() methods appear to be thread safe * judging by inspection of the source code. Likewise for its parsing methods * get<var>X</var>(Uri).</p> * * <h3 id='HttpResponseCache-TS'>HttpResponseCache thread safety (HttpResponseCache-TS)</h3> * * <p><a href='http://developer.android.com/reference/android/net/http/HttpResponseCache.html' target='_top' * >HttpResponseCache</a> appears to be thread safe judging by inspection of its source code.</p> * * <h3 id='ParcelReuse'>Parcel reuse (ParcelReuse)</h3> * * <p><a href='http://developer.android.com/reference/android/os/Parcel.html' target='_top'>Parcel</a>.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.</p> * * <h3 id='Parcel-TS'>Parcel thread safety (Parcel-TS)</h3> * * <p><a href='http://developer.android.com/reference/android/os/Parcel.html' target='_top' * >Parcel</a>.obtain and .recycle methods appear to be thread safe judging by inspection * of the source code.</p> * * <h3 id='Resources-TS'>Resources thread safety (Resources-TS)</h3> * * <p><a href='http://developer.android.com/reference/android/content/res/Resources.html' target='_top' * >Resources</a> 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”.</p> * * <h3 id='FreezeSync'>Thread synchronization by final freezing (FreezeSync)</h3> * * <p>“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.” * (<a href='http://docs.oracle.com/javase/specs/jls/se8/html/jls-17.html#jls-17.5' target='_top'>17.5</a>) * That’s an attempt to summarize the ‘freeze’ rule for final fields * (<a href='http://docs.oracle.com/javase/specs/jls/se8/html/jls-17.html#jls-17.5.1' target='_top'>17.5.1</a>), * which is difficult to parse. See also * <a href='http://tech.puredanger.com/2008/11/26/jmm-and-final-field-freeze' target='_top'>JMM and final field freeze</a>.</p> * * <p>In other words, given a fully constructed and properly referenced instance, a read from one of * its final fields <i>happens-after</i> 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.</p> * * <h3 id='StartSync'>Thread synchronization by starting (StartSync)</h3> * * <p>“A call to start() on a thread <i>happens-before</i> any actions in the started thread.” * (<a href='http://docs.oracle.com/javase/specs/jls/se8/html/jls-17.html#jls-17.4.5' target='_top'>17.4.5</a>) * Therefore when thread T1 starts thread T2, it thereby ensures that every previous * action of T1 is visible to all subsequent actions of T2.</p> * * <h3 id='TermSync'>Thread synchronization by termination detecting (TermSync)</h3> * * <p>“The final action in a thread T1 <i>synchronizes-with</i> any action in another * thread T2 that detects that T1 has terminated.” (Java language specification, * <a href='http://docs.oracle.com/javase/specs/jls/se8/html/jls-17.html#jls-17.4.4' target='_top'>17.4.4</a>) * “T2 may accomplish this by calling T1.isAlive() or T1.join().” So T2 ensures that * every previous action of T1 <i>happens-before</i> the moment of detection and is * thereby visible to all subsequent actions of T2.</p> * * <p>“All actions in a thread <i>happen-before</i> any other thread successfully returns * from a join() on that thread.” * (<a href='http://docs.oracle.com/javase/specs/jls/se8/html/jls-17.html#jls-17.4.5' target='_top'>17.4.5</a>) * </p> */ package waymaker.gen; // Copyright © 2015 Michael Allan. Licence MIT.