Made requested review changes.

Signed-off-by: JackAKirk <jack.kirk@codeplay.com>

Author: JackAKirk

source/adapters/hip/context.hpp

@@ -19,6 +19,44 @@
 
 typedef void (*ur_context_extended_deleter_t)(void *UserData);
 
+/// UR context mapping to a HIP context object.
+///
+/// There is no direct mapping between a HIP context and a UR context.
+/// The main differences are described below:
+///
+/// <b> HIP context vs UR context </b>
+///
+/// One of the main differences between the UR API and the HIP driver API is
+/// that the second modifies the state of the threads by assigning
+/// \c hipCtx_t objects to threads. \c hipCtx_t objects store data associated
+/// with a given device and control access to said device from the user side.
+/// UR API context are objects that are passed to functions, and not bound
+/// to threads.
+///
+/// Since the \c ur_context_handle_t can contain multiple devices, and a \c
+/// hipCtx_t refers to only a single device, the \c hipCtx_t is more tightly
+/// coupled to a \c ur_device_handle_t than a \c ur_context_handle_t. In order
+/// to remove some ambiguities about the different semantics of \c
+/// \c ur_context_handle_t and native \c hipCtx_t, we access the native \c
+/// hipCtx_t solely through the \c ur_device_handle_t class, by using the object
+/// \ref ScopedContext, which sets the active device (by setting the active
+/// native \c hipCtx_t).
+///
+/// <b> Primary vs User-defined \c hipCtx_t </b>
+///
+/// HIP has two different types of \c hipCtx_t, the Primary context, which is
+/// usable by all threads on a given process for a given device, and the
+/// aforementioned custom \c hipCtx_t s. The HIP documentation, confirmed with
+/// performance analysis, suggest using the Primary context whenever possible.
+///
+///  <b> Destructor callback </b>
+///
+///  Required to implement CP023, SYCL Extended Context Destruction,
+///  the UR Context can store a number of callback functions that will be
+///  called upon destruction of the UR Context.
+///  See proposal for details.
+///  https://github.com/codeplaysoftware/standards-proposals/blob/master/extended-context-destruction/index.md
+///
 ///
 ///  <b> Destructor callback </b>
 ///
@@ -52,7 +90,11 @@ struct ur_context_handle_t_ {
   std::atomic_uint32_t RefCount;
 
   ur_context_handle_t_(const ur_device_handle_t *Devs, uint32_t NumDevices)
-      : Devices{Devs, Devs + NumDevices}, RefCount{1} {};
+      : Devices{Devs, Devs + NumDevices}, RefCount{1} {
+    for (auto &Dev : Devices) {
+      urDeviceRetain(Dev);
+    }
+  };
 
   ~ur_context_handle_t_() {}