ipc redesing proposal

Author: lplewa

include/umf/ipc.h

@@ -18,7 +18,8 @@ extern "C" {
 #endif
 
 typedef struct umf_ipc_data_t *umf_ipc_handle_t;
-
+typedef struct umf_ipc_handler *umf_ipc_handler_t;
+typedef const struct umf_ipc_handler *umf_ipc_handler_t;
 ///
 /// @brief Returns the size of IPC handles for the specified pool.
 /// @param hPool [in] Pool handle
@@ -42,13 +43,31 @@ umf_result_t umfGetIPCHandle(const void *ptr, umf_ipc_handle_t *ipcHandle,
 /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
 umf_result_t umfPutIPCHandle(umf_ipc_handle_t ipcHandle);
 
+///
+/// @bries Retrivies an IPC handler which is used to open IPC handles.
+/// @param hpool [in] Pool handle.
+/// @param ipcHandler [out] IPC handler.
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+umf_result_t umfGetIPCHandler(umf_memory_pool_handle_t hpool,
+                              umf_const_ipc_handler_t *ipcHandler);
+
+///
+/// @brief Creates an IPC handler, which is used to open IPC handles.
+/// @param ops [in] instance of umf_memory_provider_ops_t.
+/// @param params [in] pointer to provider specific parameters. This is the same stucture that is used to create a memory provider. But some fileds may be ignored. See your memory provider documentation for details.
+/// @param ipcHandler [out] handle to the newly created IPC handler.
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+/// @details this function is should be used if user only want to open IPC handles,
+///          and do not need a memory pool, to allocate memory on client side.
+umf_result_t umfCreateIPCHandler(const umf_memory_provider_ops_t *ops,
+                                 void *params, umf_ipc_handler_t *ipcHandler);
 ///
 /// @brief Open IPC handle retrieved by umfGetIPCHandle.
-/// @param hPool [in] Pool handle where to open the the IPC handle.
+/// @param handler [in] IPC handler.
 /// @param ipcHandle [in] IPC handle.
 /// @param ptr [out] pointer to the memory in the current process.
 /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
-umf_result_t umfOpenIPCHandle(umf_memory_pool_handle_t hPool,
+umf_result_t umfOpenIPCHandle(umf_const_ipc_handler_t handler,
                               umf_ipc_handle_t ipcHandle, void **ptr);
 
 ///
@@ -57,6 +76,12 @@ umf_result_t umfOpenIPCHandle(umf_memory_pool_handle_t hPool,
 /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
 umf_result_t umfCloseIPCHandle(void *ptr);
 
+///
+/// @brief Destroys IPC handler, created by umfCreateIPCHandler.
+/// @param handler [in] IPC handler.
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+umf_result_t umfDestroyIPCHandler(umf_ipc_handler_t handler);
+
 #ifdef __cplusplus
 }
 #endif

include/umf/memory_pool.h

@@ -157,7 +157,7 @@ umf_result_t umfPoolGetLastAllocationError(umf_memory_pool_handle_t hPool);
 ///        with the usage of a memory provider is being tracked.
 /// @param ptr pointer to memory belonging to a memory pool
 /// @return Handle to a memory pool that contains ptr or NULL if pointer does not belong to any UMF pool.
-///
+/// @details returns NULL for ptrs that were open through IPC open function, as this ptr do not belong to any pool.
 umf_memory_pool_handle_t umfPoolByPtr(const void *ptr);
 
 ///

include/umf/memory_provider.h

@@ -19,7 +19,8 @@ extern "C" {
 
 /// @brief A struct containing memory provider specific set of functions
 typedef struct umf_memory_provider_t *umf_memory_provider_handle_t;
-
+typedef struct umf_ipc_handler *umf_ipc_handler_t;
+typedef const struct umf_ipc_handler *umf_ipc_handler_t;
 ///
 /// @brief Creates new memory provider.
 /// @param ops instance of umf_memory_provider_ops_t
@@ -172,21 +173,35 @@ umf_result_t
 umfMemoryProviderPutIPCHandle(umf_memory_provider_handle_t hProvider,
                               void *providerIpcData);
 
+/// check memory_provider_ops.h for more details
+umf_result_t
+umfMemoryProviderGetIpcHandler(umf_memory_provider_handle_t hProvider,
+                               umf_const_ipc_handler_t *handler);
+/// check memory_provider_ops.h for more details
+umf_result_t
+umfMemoryProviderCreateIpcHandler(const umf_memory_provider_ops_t *ops,
+                                  void *params, umf_ipc_handler_t *handler);
+/// check memory_provider_ops.h for more details
+umf_result_t
+umfMemoryProviderDestroyIpcHandler(umf_memory_provider_handle_t *hProvider);
+
 ///
 /// @brief Open IPC handle.
-/// @param hProvider [in] handle to the memory provider.
+/// @param hIpcHandler [in] handle to the ipcHandler
 /// @param providerIpcData [in] pointer to the IPC opaque data structure.
 /// @param ptr [out] pointer to the memory to be used in the current process.
+/// @param size [out][optional] size of the memory address range.
 /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
 ///         UMF_RESULT_ERROR_INVALID_ARGUMENT if providerIpcData cannot be handled by the provider.
 ///         UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
 umf_result_t
-umfMemoryProviderOpenIPCHandle(umf_memory_provider_handle_t hProvider,
-                               void *providerIpcData, void **ptr);
+umfMemoryProviderOpenIPCHandle(umf_memory_provider_handleer_t hIpcHanler,
+                               void *providerIpcData, void **ptr,
+                               size_t **size);
 
 ///
 /// @brief Close an IPC memory handle.
-/// @param hProvider [in] handle to the memory provider.
+/// @param hIpcHanler [in] handle to the memory provider.
 /// @param ptr [in] pointer returned by umfMemoryProviderOpenIPCHandle function.
 /// @param size [in] size of the memory address range.
 /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.

include/umf/memory_provider_ops.h

@@ -116,13 +116,13 @@ typedef struct umf_memory_provider_ipc_ops_t {
 
     ///
     /// @brief Open IPC handle.
-    /// @param provider pointer to the memory provider.
-    /// @param providerIpcData pointer to the IPC opaque data structure.
+    /// @param ipcHandler pointer to the memory provider.
+    /// @param providerIpc Data pointer to the IPC opaque data structure.
     /// @param ptr [out] pointer to the memory to be used in the current process.
     /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
     ///         UMF_RESULT_ERROR_INVALID_ARGUMENT if providerIpcData cannot be handled by the provider.
     ///         UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
-    umf_result_t (*open_ipc_handle)(void *provider, void *providerIpcData,
+    umf_result_t (*open_ipc_handle)(void *ipcHandler, void *providerIpcData,
                                     void **ptr);
 
     ///
@@ -133,7 +133,26 @@ typedef struct umf_memory_provider_ipc_ops_t {
     /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
     ///         UMF_RESULT_ERROR_INVALID_ARGUMENT if invalid \p ptr is passed.
     ///         UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
-    umf_result_t (*close_ipc_handle)(void *provider, void *ptr, size_t size);
+    umf_result_t (*close_ipc_handle)(void *ipcHandler, void *ptr, size_t size);
+
+    /// @brief Retrieve an IPC handler which is used to open IPC handles.
+    /// @param provider pointer to the memory provider.
+    /// @param ipcHandler [out] pointer to the IPC handler.
+    /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+    umf_result_t (*get_ipc_handler)(void *provider, void **ipcHandler);
+
+    /// @brief Creates an IPC handler, which is used to open IPC handles.
+    /// @param params provider-specific params. This argument must be the same structure then in the initialize function,
+    ///        but some fields might be ignored, if they are not needed for IPC handle.
+    /// @param ipcHandler [out] pointer to the newly created IPC handler.
+    /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+    /// @details This function create ipc handler, with is used to open IPC handles, without need to create provider, only to open handle.
+    umf_result_t (*create_ipc_handler)(void *params, void **ipcHandler);
+
+    /// @brief Destroys an IPC handler, created by create_ipc_handler.
+    /// @param ipcHandler pointer to the IPC handler.
+    /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+    umf_result_t (*destory_ipc_handler)(void *ipcHandler);
 } umf_memory_provider_ipc_ops_t;
 
 ///