Adds outward interoperability functions to core occa types. (#635)

* Adds outward interoperability functions to core occa types.

* Fixes line endings.

* Fixes line endings.

* Implements `memory::unwrap` for serial mode.

* Documents outward interoperability functions for core occa types.

Author: kris-rowe

include/occa/core/base.hpp

@@ -133,6 +133,9 @@ namespace occa {
 
   void printModeInfo();
   //====================================
+
+  template<typename T>
+  void* unwrap(T& occaType);
 }
 
 #include "base.tpp"

include/occa/core/base.tpp

@@ -12,4 +12,9 @@ namespace occa {
                           const occa::json &props) {
     return getDevice().wrapMemory(ptr, entries, occa::dtype::get<T>(), props);
   }
+
+  template<typename T>
+  void* unwrap(T& occaType) {
+    return occaType.unwrap();
+  }
 }

include/occa/core/device.hpp

@@ -730,6 +730,23 @@ namespace occa {
     experimental::memoryPool createMemoryPool(const occa::json &props = occa::json());
 
     //  |===============================
+
+    /**
+     * @startDoc{unwrap}
+     * 
+     * Description:
+     *   Retreives the mode-specific object associated with this [[device]].
+     *   The lifetime of the returned object is the same as this device.
+     *   Destruction of the returned object during this device's lifetime results in undefined behavior.   
+     *  
+     *   > An OCCA application is responsible for correctly converting the returned `void*` pointer to the corresponding mode-specific device type.
+     *   
+     * Returns:
+     *   A pointer to the mode-specific object associated with this device.
+     * 
+     * @endDoc
+    */
+    void* unwrap();
   };
 
   template <>

include/occa/core/memory.hpp

@@ -460,6 +460,23 @@ namespace occa {
     void free();
 
     void detach();
+
+    /**
+     * @startDoc{unwrap}
+     * 
+     * Description:
+     *   Retreives the mode-specific object associated with this [[stream]].
+     *   The lifetime of the returned object is the same as this stream.
+     *   Destruction of the returned object during this stream's lifetime results in undefined behavior.   
+     *  
+     *   > An OCCA application is responsible for correctly converting the returned `void*` pointer to the corresponding mode-specific stream type.
+     * 
+     * Returns:
+     *   A pointer to the mode-specific object associated with this stream.
+     * 
+     * @endDoc
+    */
+    void* unwrap();
   };
 
   extern memory null;

include/occa/core/stream.hpp

@@ -147,6 +147,23 @@ namespace occa {
      * @endDoc
      */
     void finish();
+
+    /**
+     * @startDoc{unwrap}
+     * 
+     * Description:
+     *   Retreives the mode-specific object associated with this [[memory]].
+     *   The lifetime of the returned object is the same as this memory.
+     *   Destruction of the returned object during this memory's lifetime results in undefined behavior.   
+     *  
+     *   > An OCCA application is responsible for correctly converting the returned `void*` pointer to the corresponding mode-specific memory type.
+     * 
+     * Returns:
+     *   A pointer to the mode-specific object associated with this stream.
+     * 
+     * @endDoc
+    */
+    void* unwrap();
   };
 
   std::ostream& operator << (std::ostream &out,

include/occa/core/streamTag.hpp

@@ -122,6 +122,23 @@ namespace occa {
      * @endDoc
      */
     void free();
+
+    /**
+     * @startDoc{unwrap}
+     * 
+     * Description:
+     *   Retreives the mode-specific object associated with this [[streamTag]].
+     *   The lifetime of the returned object is the same as this streamTag.
+     *   Destruction of the returned object during this streamTag's lifetime results in undefined behavior.   
+     *  
+     *   > An OCCA application is responsible for correctly converting the returned `void*` pointer to the corresponding mode-specific streamTag type.
+     * 
+     * Returns:
+     *   A pointer to the mode-specific object associated with this streamTag
+     * 
+     * @endDoc
+    */
+    void* unwrap();
   };
 }
 

src/core/device.cpp

@@ -535,6 +535,13 @@ namespace occa {
   }
   //  |=================================
 
+  void* device::unwrap() {
+    assertInitialized();
+    return modeDevice->unwrap();
+  }
+
+  //  |=================================
+
   template <>
   hash_t hash(const occa::device &device) {
     return device.hash();

src/core/memory.cpp

@@ -338,6 +338,11 @@ namespace occa {
     modeMemory = nullptr;
   }
 
+  void* memory::unwrap() {
+    assertInitialized();
+    return modeMemory->unwrap();
+  }
+
   memory null;
 
   std::ostream& operator << (std::ostream &out,

src/core/stream.cpp

@@ -102,6 +102,14 @@ namespace occa {
     if(modeStream) modeStream->finish();
   }
 
+  void* stream::unwrap() {
+    OCCA_ERROR(
+      "stream::unwrap: stream is uninitialized or has been free'd",
+      nullptr != modeStream
+    );
+    return modeStream->unwrap();
+  }
+
   std::ostream& operator << (std::ostream &out,
                              const occa::stream &stream) {
     out << stream.properties();

src/core/streamTag.cpp

@@ -89,4 +89,12 @@ namespace occa {
     delete modeStreamTag;
     modeStreamTag = NULL;
   }
+
+  void* streamTag::unwrap() {
+    OCCA_ERROR(
+      "streamTag::unwrap: stream is uninitialized or has been free'd",
+      nullptr != modeStreamTag
+    );
+    return modeStreamTag->unwrap();
+  }
 }