[STF] Use opaque struct pointers for C API handles (#8205)

Replace `typedef void*` with `typedef struct <name>_t* <name>` for all
opaque handle types in the STF C API. This provides type safety at the
C level, preventing accidental mixing of different handle types.

The naming convention (e.g. stf_ctx_handle_t / stf_ctx_handle) matches
the Cython declarations in the stf_c_api branch for consistency.

Made-with: Cursor

Author: caugonnet

c/experimental/stf/include/cccl/c/experimental/stf/stf.h

@@ -235,7 +235,7 @@ typedef struct stf_dim4
 typedef stf_pos4 (*stf_get_executor_fn)(stf_pos4 data_coords, stf_dim4 data_dims, stf_dim4 grid_dims);
 
 //! \brief Opaque handle for an execution place grid (e.g. one place per stream).
-typedef void* stf_exec_place_grid_handle;
+typedef struct stf_exec_place_grid_handle_t* stf_exec_place_grid_handle;
 
 //! \}
 
@@ -414,31 +414,31 @@ void stf_exec_place_grid_destroy(stf_exec_place_grid_handle grid);
 //! Context stores the state of the STF library and serves as entry point for all API calls.
 //! Must be created with stf_ctx_create() or stf_ctx_create_graph() and destroyed with stf_ctx_finalize().
 
-typedef void* stf_ctx_handle;
+typedef struct stf_ctx_handle_t* stf_ctx_handle;
 
 //!
 //! \brief Opaque handle for logical data
 //!
 //! Represents abstract data that may exist in multiple memory locations.
 //! Created with stf_logical_data() or stf_logical_data_empty() and destroyed with stf_logical_data_destroy().
 
-typedef void* stf_logical_data_handle;
+typedef struct stf_logical_data_handle_t* stf_logical_data_handle;
 
 //!
 //! \brief Opaque handle for task
 //!
 //! Represents a computational task that operates on logical data.
 //! Created with stf_task_create() and destroyed with stf_task_destroy().
 
-typedef void* stf_task_handle;
+typedef struct stf_task_handle_t* stf_task_handle;
 
 //!
 //! \brief Opaque handle for CUDA kernel task
 //!
 //! Specialized task optimized for CUDA kernel execution.
 //! Created with stf_cuda_kernel_create() and destroyed with stf_cuda_kernel_destroy().
 
-typedef void* stf_cuda_kernel_handle;
+typedef struct stf_cuda_kernel_handle_t* stf_cuda_kernel_handle;
 
 //! \}
 

c/experimental/stf/src/stf.cu

@@ -58,7 +58,7 @@ static data_place to_data_place(const stf_data_place* data_p)
       {
         return data_place::invalid();
       }
-      auto grid_ptr = static_cast<exec_place*>(grid_handle);
+      auto* grid_ptr = reinterpret_cast<exec_place*>(grid_handle);
       // Layout-compatible: pass C mapper directly so the runtime calls it
       partition_fn_t cpp_mapper = reinterpret_cast<partition_fn_t>(mapper);
       return data_place::composite(cpp_mapper, *grid_ptr);
@@ -73,27 +73,27 @@ static data_place to_data_place(const stf_data_place* data_p)
 void stf_ctx_create(stf_ctx_handle* ctx)
 {
   _CCCL_ASSERT(ctx != nullptr, "context handle pointer must not be null");
-  *ctx = new context{};
+  *ctx = reinterpret_cast<stf_ctx_handle>(new context{});
 }
 
 void stf_ctx_create_graph(stf_ctx_handle* ctx)
 {
   _CCCL_ASSERT(ctx != nullptr, "context handle pointer must not be null");
-  *ctx = new context{graph_ctx()};
+  *ctx = reinterpret_cast<stf_ctx_handle>(new context{graph_ctx()});
 }
 
 void stf_ctx_finalize(stf_ctx_handle ctx)
 {
   _CCCL_ASSERT(ctx != nullptr, "context handle must not be null");
-  auto* context_ptr = static_cast<context*>(ctx);
+  auto* context_ptr = reinterpret_cast<context*>(ctx);
   context_ptr->finalize();
   delete context_ptr;
 }
 
 cudaStream_t stf_fence(stf_ctx_handle ctx)
 {
   _CCCL_ASSERT(ctx != nullptr, "context handle must not be null");
-  auto* context_ptr = static_cast<context*>(ctx);
+  auto* context_ptr = reinterpret_cast<context*>(ctx);
   return context_ptr->fence();
 }
 
@@ -109,7 +109,7 @@ void stf_logical_data_with_place(
   _CCCL_ASSERT(ctx != nullptr, "context handle pointer must not be null");
   _CCCL_ASSERT(ld != nullptr, "logical data handle pointer must not be null");
 
-  auto* context_ptr = static_cast<context*>(ctx);
+  auto* context_ptr = reinterpret_cast<context*>(ctx);
 
   // Convert C data_place to C++ data_place
   cuda::experimental::stf::data_place cpp_dplace;
@@ -141,23 +141,23 @@ void stf_logical_data_with_place(
   auto ld_typed = context_ptr->logical_data(make_slice((char*) addr, sz), cpp_dplace);
 
   // Store the logical_data_untyped directly as opaque pointer
-  *ld = new logical_data_untyped{ld_typed};
+  *ld = reinterpret_cast<stf_logical_data_handle>(new logical_data_untyped{ld_typed});
 }
 
 void stf_logical_data_set_symbol(stf_logical_data_handle ld, const char* symbol)
 {
   _CCCL_ASSERT(ld != nullptr, "logical data handle must not be null");
   _CCCL_ASSERT(symbol != nullptr, "symbol string must not be null");
 
-  auto* ld_ptr = static_cast<logical_data_untyped*>(ld);
+  auto* ld_ptr = reinterpret_cast<logical_data_untyped*>(ld);
   ld_ptr->set_symbol(symbol);
 }
 
 void stf_logical_data_destroy(stf_logical_data_handle ld)
 {
   _CCCL_ASSERT(ld != nullptr, "logical data handle must not be null");
 
-  auto* ld_ptr = static_cast<logical_data_untyped*>(ld);
+  auto* ld_ptr = reinterpret_cast<logical_data_untyped*>(ld);
   delete ld_ptr;
 }
 
@@ -166,18 +166,18 @@ void stf_logical_data_empty(stf_ctx_handle ctx, size_t length, stf_logical_data_
   _CCCL_ASSERT(ctx != nullptr, "context handle must not be null");
   _CCCL_ASSERT(to != nullptr, "logical data output pointer must not be null");
 
-  auto* context_ptr = static_cast<context*>(ctx);
+  auto* context_ptr = reinterpret_cast<context*>(ctx);
   auto ld_typed     = context_ptr->logical_data(shape_of<slice<char>>(length));
-  *to               = new logical_data_untyped{ld_typed};
+  *to               = reinterpret_cast<stf_logical_data_handle>(new logical_data_untyped{ld_typed});
 }
 
 void stf_token(stf_ctx_handle ctx, stf_logical_data_handle* ld)
 {
   _CCCL_ASSERT(ctx != nullptr, "context handle must not be null");
   _CCCL_ASSERT(ld != nullptr, "logical data handle output pointer must not be null");
 
-  auto* context_ptr = static_cast<context*>(ctx);
-  *ld               = new logical_data_untyped{context_ptr->token()};
+  auto* context_ptr = reinterpret_cast<context*>(ctx);
+  *ld               = reinterpret_cast<stf_logical_data_handle>(new logical_data_untyped{context_ptr->token()});
 }
 
 /* Convert the C-API stf_exec_place to a C++ exec_place object */
@@ -204,16 +204,16 @@ void stf_task_create(stf_ctx_handle ctx, stf_task_handle* t)
   _CCCL_ASSERT(ctx != nullptr, "context handle must not be null");
   _CCCL_ASSERT(t != nullptr, "task handle output pointer must not be null");
 
-  auto* context_ptr = static_cast<context*>(ctx);
-  *t                = new context::unified_task<>{context_ptr->task()};
+  auto* context_ptr = reinterpret_cast<context*>(ctx);
+  *t                = reinterpret_cast<stf_task_handle>(new context::unified_task<>{context_ptr->task()});
 }
 
 void stf_task_set_exec_place(stf_task_handle t, stf_exec_place* exec_p)
 {
   _CCCL_ASSERT(t != nullptr, "task handle must not be null");
   _CCCL_ASSERT(exec_p != nullptr, "exec_place pointer must not be null");
 
-  auto* task_ptr = static_cast<context::unified_task<>*>(t);
+  auto* task_ptr = reinterpret_cast<context::unified_task<>*>(t);
   task_ptr->set_exec_place(to_exec_place(exec_p));
 }
 
@@ -222,7 +222,7 @@ void stf_task_set_symbol(stf_task_handle t, const char* symbol)
   _CCCL_ASSERT(t != nullptr, "task handle must not be null");
   _CCCL_ASSERT(symbol != nullptr, "symbol string must not be null");
 
-  auto* task_ptr = static_cast<context::unified_task<>*>(t);
+  auto* task_ptr = reinterpret_cast<context::unified_task<>*>(t);
   task_ptr->set_symbol(symbol);
 }
 
@@ -231,8 +231,8 @@ void stf_task_add_dep(stf_task_handle t, stf_logical_data_handle ld, stf_access_
   _CCCL_ASSERT(t != nullptr, "task handle must not be null");
   _CCCL_ASSERT(ld != nullptr, "logical data handle must not be null");
 
-  auto* task_ptr = static_cast<context::unified_task<>*>(t);
-  auto* ld_ptr   = static_cast<logical_data_untyped*>(ld);
+  auto* task_ptr = reinterpret_cast<context::unified_task<>*>(t);
+  auto* ld_ptr   = reinterpret_cast<logical_data_untyped*>(ld);
   task_ptr->add_deps(task_dep_untyped(*ld_ptr, access_mode(m)));
 }
 
@@ -243,16 +243,16 @@ void stf_task_add_dep_with_dplace(
   _CCCL_ASSERT(ld != nullptr, "logical data handle must not be null");
   _CCCL_ASSERT(data_p != nullptr, "data_place pointer must not be null");
 
-  auto* task_ptr = static_cast<context::unified_task<>*>(t);
-  auto* ld_ptr   = static_cast<logical_data_untyped*>(ld);
+  auto* task_ptr = reinterpret_cast<context::unified_task<>*>(t);
+  auto* ld_ptr   = reinterpret_cast<logical_data_untyped*>(ld);
   task_ptr->add_deps(task_dep_untyped(*ld_ptr, access_mode(m), to_data_place(data_p)));
 }
 
 void* stf_task_get(stf_task_handle t, int index)
 {
   _CCCL_ASSERT(t != nullptr, "task handle must not be null");
 
-  auto* task_ptr = static_cast<context::unified_task<>*>(t);
+  auto* task_ptr = reinterpret_cast<context::unified_task<>*>(t);
   auto s         = task_ptr->template get<slice<const char>>(index);
   return (void*) s.data_handle();
 }
@@ -261,39 +261,39 @@ void stf_task_start(stf_task_handle t)
 {
   _CCCL_ASSERT(t != nullptr, "task handle must not be null");
 
-  auto* task_ptr = static_cast<context::unified_task<>*>(t);
+  auto* task_ptr = reinterpret_cast<context::unified_task<>*>(t);
   task_ptr->start();
 }
 
 void stf_task_end(stf_task_handle t)
 {
   _CCCL_ASSERT(t != nullptr, "task handle must not be null");
 
-  auto* task_ptr = static_cast<context::unified_task<>*>(t);
+  auto* task_ptr = reinterpret_cast<context::unified_task<>*>(t);
   task_ptr->end();
 }
 
 void stf_task_enable_capture(stf_task_handle t)
 {
   _CCCL_ASSERT(t != nullptr, "task handle must not be null");
 
-  auto* task_ptr = static_cast<context::unified_task<>*>(t);
+  auto* task_ptr = reinterpret_cast<context::unified_task<>*>(t);
   task_ptr->enable_capture();
 }
 
 CUstream stf_task_get_custream(stf_task_handle t)
 {
   _CCCL_ASSERT(t != nullptr, "task handle must not be null");
 
-  auto* task_ptr = static_cast<context::unified_task<>*>(t);
+  auto* task_ptr = reinterpret_cast<context::unified_task<>*>(t);
   return static_cast<CUstream>(task_ptr->get_stream());
 }
 
 void stf_task_destroy(stf_task_handle t)
 {
   _CCCL_ASSERT(t != nullptr, "task handle must not be null");
 
-  auto* task_ptr = static_cast<context::unified_task<>*>(t);
+  auto* task_ptr = reinterpret_cast<context::unified_task<>*>(t);
   delete task_ptr;
 }
 
@@ -319,9 +319,9 @@ void stf_cuda_kernel_create(stf_ctx_handle ctx, stf_cuda_kernel_handle* k)
   _CCCL_ASSERT(ctx != nullptr, "context handle must not be null");
   _CCCL_ASSERT(k != nullptr, "cuda kernel handle output pointer must not be null");
 
-  auto* context_ptr = static_cast<context*>(ctx);
+  auto* context_ptr = reinterpret_cast<context*>(ctx);
   using kernel_type = decltype(context_ptr->cuda_kernel());
-  *k                = new kernel_type{context_ptr->cuda_kernel()};
+  *k                = reinterpret_cast<stf_cuda_kernel_handle>(new kernel_type{context_ptr->cuda_kernel()});
 }
 
 void stf_cuda_kernel_set_exec_place(stf_cuda_kernel_handle k, stf_exec_place* exec_p)
@@ -330,7 +330,7 @@ void stf_cuda_kernel_set_exec_place(stf_cuda_kernel_handle k, stf_exec_place* ex
   _CCCL_ASSERT(exec_p != nullptr, "exec_place pointer must not be null");
 
   using kernel_type = decltype(::std::declval<context>().cuda_kernel());
-  auto* kernel_ptr  = static_cast<kernel_type*>(k);
+  auto* kernel_ptr  = reinterpret_cast<kernel_type*>(k);
   kernel_ptr->set_exec_place(to_exec_place(exec_p));
 }
 
@@ -340,7 +340,7 @@ void stf_cuda_kernel_set_symbol(stf_cuda_kernel_handle k, const char* symbol)
   _CCCL_ASSERT(symbol != nullptr, "symbol string must not be null");
 
   using kernel_type = decltype(::std::declval<context>().cuda_kernel());
-  auto* kernel_ptr  = static_cast<kernel_type*>(k);
+  auto* kernel_ptr  = reinterpret_cast<kernel_type*>(k);
   kernel_ptr->set_symbol(symbol);
 }
 
@@ -350,8 +350,8 @@ void stf_cuda_kernel_add_dep(stf_cuda_kernel_handle k, stf_logical_data_handle l
   _CCCL_ASSERT(ld != nullptr, "logical data handle must not be null");
 
   using kernel_type = decltype(::std::declval<context>().cuda_kernel());
-  auto* kernel_ptr  = static_cast<kernel_type*>(k);
-  auto* ld_ptr      = static_cast<logical_data_untyped*>(ld);
+  auto* kernel_ptr  = reinterpret_cast<kernel_type*>(k);
+  auto* ld_ptr      = reinterpret_cast<logical_data_untyped*>(ld);
   kernel_ptr->add_deps(task_dep_untyped(*ld_ptr, access_mode(m)));
 }
 
@@ -360,7 +360,7 @@ void stf_cuda_kernel_start(stf_cuda_kernel_handle k)
   _CCCL_ASSERT(k != nullptr, "cuda kernel handle must not be null");
 
   using kernel_type = decltype(::std::declval<context>().cuda_kernel());
-  auto* kernel_ptr  = static_cast<kernel_type*>(k);
+  auto* kernel_ptr  = reinterpret_cast<kernel_type*>(k);
   kernel_ptr->start();
 }
 
@@ -376,7 +376,7 @@ void stf_cuda_kernel_add_desc_cufunc(
   _CCCL_ASSERT(k != nullptr, "cuda kernel handle must not be null");
 
   using kernel_type = decltype(::std::declval<context>().cuda_kernel());
-  auto* kernel_ptr  = static_cast<kernel_type*>(k);
+  auto* kernel_ptr  = reinterpret_cast<kernel_type*>(k);
 
   cuda_kernel_desc desc;
   desc.configure_raw(cufunc, grid_dim_, block_dim_, shared_mem_, arg_cnt, args);
@@ -388,7 +388,7 @@ void* stf_cuda_kernel_get_arg(stf_cuda_kernel_handle k, int index)
   _CCCL_ASSERT(k != nullptr, "cuda kernel handle must not be null");
 
   using kernel_type = decltype(::std::declval<context>().cuda_kernel());
-  auto* kernel_ptr  = static_cast<kernel_type*>(k);
+  auto* kernel_ptr  = reinterpret_cast<kernel_type*>(k);
   auto s            = kernel_ptr->template get<slice<const char>>(index);
   return (void*) (s.data_handle());
 }
@@ -398,7 +398,7 @@ void stf_cuda_kernel_end(stf_cuda_kernel_handle k)
   _CCCL_ASSERT(k != nullptr, "cuda kernel handle must not be null");
 
   using kernel_type = decltype(::std::declval<context>().cuda_kernel());
-  auto kernel_ptr   = static_cast<kernel_type*>(k);
+  auto kernel_ptr   = reinterpret_cast<kernel_type*>(k);
   kernel_ptr->end();
 }
 
@@ -407,7 +407,7 @@ void stf_cuda_kernel_destroy(stf_cuda_kernel_handle t)
   _CCCL_ASSERT(t != nullptr, "cuda kernel handle must not be null");
 
   using kernel_type = decltype(::std::declval<context>().cuda_kernel());
-  auto* kernel_ptr  = static_cast<kernel_type*>(t);
+  auto* kernel_ptr  = reinterpret_cast<kernel_type*>(t);
   delete kernel_ptr;
 }
 
@@ -425,7 +425,7 @@ stf_exec_place_grid_handle stf_exec_place_grid_from_devices(const int* device_id
   {
     places.push_back(exec_place::device(device_ids[i]));
   }
-  return new exec_place(make_grid(::std::move(places)));
+  return reinterpret_cast<stf_exec_place_grid_handle>(new exec_place(make_grid(::std::move(places))));
 }
 
 stf_exec_place_grid_handle
@@ -441,14 +441,14 @@ stf_exec_place_grid_create(const stf_exec_place* places, size_t count, const stf
   exec_place grid = (grid_dims != nullptr)
                     ? make_grid(::std::move(cpp_places), dim4(grid_dims->x, grid_dims->y, grid_dims->z, grid_dims->t))
                     : make_grid(::std::move(cpp_places));
-  return new exec_place(::std::move(grid));
+  return reinterpret_cast<stf_exec_place_grid_handle>(new exec_place(::std::move(grid)));
 }
 
 void stf_exec_place_grid_destroy(stf_exec_place_grid_handle grid)
 {
   if (grid != nullptr)
   {
-    delete static_cast<exec_place*>(grid);
+    delete reinterpret_cast<exec_place*>(grid);
   }
 }