add changelog entry for issue 16230

changelog/atomicLoad-returns-shared.dd

@@ -0,0 +1,34 @@
+`core.atomic.atomicLoad` now returns a `shared` result for aggregate types that have indirections.
+
+$(REF atomicLoad, core,atomic) used to strip the `shared` qualifier off too
+eagerly. When an aggregate type has a "head" and a "tail", connected by an
+indirection, then `atomicLoad` used to strip `shared` off the tail. That was a
+bug ($(BUGZILLA 16230)). `atomicLoad` only loads the head. The tail remains in
+shared memory, and must keep the `shared` qualifier.
+
+`atomicLoad` now leaves the `shared` qualifier on when loading such types
+(classes, structs with pointer fields). Head and tail cannot be qualified
+independently, so the head remains typed as `shared` even though it is being
+copied from shared to thread-local memory.
+
+In order to access the head, the `shared` qualifier can safely be casted away
+from the result of `atomicLoad`. It is not safe to access the tail this way.
+
+Example:
+----
+struct S { int head; int* tailPointer; }
+
+shared int tail = 1;
+auto shs = shared S(2, &tail);
+
+void main()
+{
+    import core.atomic : atomicLoad;
+    shared S s = atomicLoad(shs);
+
+    ++(cast(S) s).head; // Ok, reading/writing thread-local head.
+
+    version (none) int* t = s.tailPointer; // Doesn't compile anymore.
+    shared(int)* t = s.tailPointer; // Ok, target of the pointer is shared.
+}
+----