Fix Issue 14932 - spec does not define what shared attribute does (#3556)

* Fix Issue 14932 - language spec does not define what shared does

Normal initialization of shared vars is OK.
Add atomicStore, atomicLoad example.
Add example showing casting to shared.
Mention shared globals use common storage not TLS.

* Only mutable globals are thread-local by default

Author: ntrel

spec/attribute.dd

@@ -520,9 +520,7 @@ $(H2 $(LNAME2 shared-storage, Shared Storage Attributes))
 
 $(H3 $(LNAME2 shared, $(D shared) Attribute))
 
-        $(P The $(DDSUBLINK spec/const3, shared, $(D shared) attribute) modifies the type from $(D T) to $(D shared(T)),
-        the same way as $(D const) does.
-        )
+        $(P See $(DDSUBLINK spec/const3, shared, $(D shared)).)
 
 $(H3 $(LNAME2 gshared, $(D __gshared) Attribute))
 

spec/const3.dd

@@ -577,24 +577,67 @@ x.atomicOp!"+="(1);
 )
 $(P $(RED Warning:) An individual read or write operation on shared
 data is not an error yet by default. To detect these, use the
-`-preview=nosharedaccess` compiler option.)
+`-preview=nosharedaccess` compiler option. Normal initialization is
+allowed without an error.)
+
+$(SPEC_RUNNABLE_EXAMPLE_RUN
+---
+import core.atomic;
+
+int y;
+shared int x = y; // OK
+
+//x = 5; // write error with preview flag
+x.atomicStore(5); // OK
+//y = x; // read error with preview flag
+y = x.atomicLoad(); // OK
+assert(y == 5);
+---
+)
+
+$(H3 $(LNAME2 shared_cast, Casting))
 
 $(P When working with larger types, manual synchronization
 can be used. To do that, `shared` can be cast away for the
 duration while mutual exclusion has been established:
 )
+
 $(SPEC_RUNNABLE_EXAMPLE_COMPILE
 ---
 struct T;
 shared T* x;
+
 synchronized
 {
     T* p = cast(T*)x;
     // operate on `*p`
 }
 ---
 )
-$(P Lastly, to declare global/static data to be implicitly shared across
+
+$(P An unshared reference can be cast to shared only if the source data
+will not be accessed for the lifetime of the cast result.)
+
+$(SPEC_RUNNABLE_EXAMPLE_COMPILE
+---
+class C {}
+
+@trusted shared(C) create()
+{
+    auto c = new C;
+    // work with c without it escaping
+    return cast(shared)c; // OK
+}
+---
+)
+
+$(H3 $(LNAME2 shared_global, Shared Global Variables))
+
+$(P Global (or static) shared variables are stored in common storage which
+is accessible across threads. Global mutable variables are stored in
+thread-local storage by default.)
+
+$(P To declare global/static data to be implicitly shared across
 multiple threads without any compiler checks, see $(DDSUBLINK
 spec/attribute, gshared, `__gshared`).
 )