[C++ for OpenCL] Make dtors with named address spaces optional. (#736)

This feature was not fully supported by clang and got
de-prioritized from the release due to the following:
- global dtors were not supported originally.
- private and local address spaces can be supported
  through generic address space.
- local dtors can't be invoked automatically and object in this
  address space are pseudo-global anyway.

The WIP implementation review for supporting this feature can be
tracked through: https://reviews.llvm.org/D109609.

Author: AnastasiaStulova

cxx4opencl/address_spaces.txt

@@ -337,11 +337,6 @@ constructors and destructors, the implementation defines an ABI format for
 runtime initialization and destruction of global objects before/after all
 kernels are enqueued.
 
-Non-trivial destructors for global objects are not required to be supported
-by all implementations. The macro `__opencl_cpp_global_destructor`,
-which is defined if and only if such destructors are supported by the implementation,
-can be used to check whether this functionality is available when compiling kernel code.
-
 Objects in `__local` address space can not have initializers in
 declarations and therefore a constructor can not be called. All objects
 created in the local address space have undefined state at the point of
@@ -395,6 +390,41 @@ __constant C1 cobj2 = C1();
 __constant C2 cobj3(1);
 ------------
 
+Non-trivial destructors for objects in non-default address spaces (i.e. all
+other than generic address space) are not required to be supported by
+implementations. The macro `+__opencl_cpp_destructor_with_address_spaces+`,
+which is defined if and only if such destructors are supported by an
+implementation, can be used to check whether this functionality can be used
+in kernel sources. Additionally destructors with global objects might not be
+supported even if address spaces are supported with destructors in general.
+Such functionality is indicated by the presence of the
+`+__opencl_cpp_global_destructor+` macro. If the macro
+`+__opencl_cpp_global_destructor+` is defined then
+`+__opencl_cpp_destructor_with_address_spaces+` must also be defined. Note that
+the destruction of objects in named address spaces global, local, or private
+can be performed using destructors with default address space (i.e. generic)
+by utilising address space conversions.
+
+[source,cpp]
+------------
+1   class C {
+2   public:
+3   #ifdef __opencl_cpp_destructor_with_address_spaces
+4     ~C() __local;
+5   #else
+6     ~C();
+7   #endif
+8   };
+9
+10  kernel void foo() {
+11    __local C locobj;
+12    locobj.~C();    // uses destructor in local address space (on line 4)
+13                    // if such destructors are supported,
+14                    // otherwise uses generic address space destructor (on line 6)
+15                    // converting to generic address prior to call into destructor.
+16  }
+------------
+
 ==== Nested pointers
 
 {cpp} for OpenCL does not allow implicit address space conversions in nested