Add Safety comments and clippy::missing_safety_doc for issue #26

src/command_queue.rs

@@ -15,7 +15,7 @@
 //! OpenCL Command Queue API.
 
 #![allow(non_camel_case_types, deprecated)]
-#![allow(clippy::too_many_arguments, clippy::not_unsafe_ptr_arg_deref)]
+#![allow(clippy::too_many_arguments, clippy::not_unsafe_ptr_arg_deref, clippy::missing_safety_doc)]
 
 pub use opencl_sys::{
     cl_bool, cl_command_queue, cl_command_queue_info, cl_command_queue_properties, cl_context,

src/gl.rs

@@ -15,7 +15,7 @@
 //! OpenCL OpenGl Interoperability API.
 
 #![allow(non_camel_case_types, deprecated)]
-#![allow(clippy::not_unsafe_ptr_arg_deref)]
+#![allow(clippy::not_unsafe_ptr_arg_deref, clippy::missing_safety_doc)]
 
 pub use opencl_sys::{
     cl_GLenum, cl_GLint, cl_GLsync, cl_GLuint, cl_command_queue, cl_context, cl_context_properties,

src/kernel.rs

@@ -185,6 +185,10 @@ pub unsafe fn release_kernel(kernel: cl_kernel) -> Result<(), cl_int> {
 /// * `arg_ptr` - pointer to the data for the argument at arg_index.
 ///
 /// returns an empty Result or the error code from the OpenCL C API function.
+/// 
+/// # Safety
+///
+/// This function is unsafe because arg must match the kernel argument.
 #[inline]
 pub unsafe fn set_kernel_arg(
     kernel: cl_kernel,
@@ -208,6 +212,10 @@ pub unsafe fn set_kernel_arg(
 /// * `arg_ptr` - the SVM pointer to the data for the argument at arg_index.
 ///
 /// returns an empty Result or the error code from the OpenCL C API function.
+/// 
+/// # Safety
+///
+/// This function is unsafe because arg must match the kernel argument.
 #[cfg(feature = "CL_VERSION_2_0")]
 #[inline]
 pub unsafe fn set_kernel_arg_svm_pointer(
@@ -232,6 +240,10 @@ pub unsafe fn set_kernel_arg_svm_pointer(
 /// * `param_ptr` - pointer to the data for the param_name.
 ///
 /// returns an empty Result or the error code from the OpenCL C API function.
+/// 
+/// # Safety
+///
+/// This function is unsafe because param must match the kernel argument.
 #[cfg(feature = "CL_VERSION_2_0")]
 #[inline]
 pub unsafe fn set_kernel_exec_info(

src/memory.rs

@@ -75,6 +75,10 @@ use std::ptr;
 ///
 /// returns a Result containing the new OpenCL buffer object
 /// or the error code from the OpenCL C API function.
+///
+/// # Safety
+///
+/// This function is unsafe because incorrect `flags` can cause undefined behaviour.
 #[inline]
 pub unsafe fn create_buffer(
     context: cl_context,
@@ -104,6 +108,10 @@ pub unsafe fn create_buffer(
 ///
 /// returns a Result containing the new OpenCL buffer object
 /// or the error code from the OpenCL C API function.
+///
+/// # Safety
+///
+/// This function is unsafe because incorrect `flags` can cause undefined behaviour.
 #[inline]
 pub unsafe fn create_sub_buffer(
     buffer: cl_mem,
@@ -142,6 +150,10 @@ pub unsafe fn create_sub_buffer(
 ///
 /// returns a Result containing the new OpenCL image object
 /// or the error code from the OpenCL C API function.
+///
+/// # Safety
+///
+/// This function is unsafe because incorrect `flags` can cause undefined behaviour.
 #[cfg(feature = "CL_VERSION_1_2")]
 #[inline]
 pub unsafe fn create_image(
@@ -181,6 +193,10 @@ pub unsafe fn create_image(
 ///
 /// returns a Result containing the new OpenCL pipe object
 /// or the error code from the OpenCL C API function.
+///
+/// # Safety
+///
+/// This function is unsafe because incorrect `flags` can cause undefined behaviour.
 #[cfg(feature = "CL_VERSION_2_0")]
 #[inline]
 pub unsafe fn create_pipe(
@@ -221,6 +237,10 @@ pub unsafe fn create_pipe(
 ///
 /// returns a Result containing the new OpenCL buffer object
 /// or the error code from the OpenCL C API function.
+///
+/// # Safety
+///
+/// This function is unsafe because incorrect `flags` can cause undefined behaviour.
 #[cfg(feature = "CL_VERSION_3_0")]
 #[inline]
 pub unsafe fn create_buffer_with_properties(
@@ -258,6 +278,10 @@ pub unsafe fn create_buffer_with_properties(
 ///
 /// returns a Result containing the new OpenCL image object
 /// or the error code from the OpenCL C API function.
+///
+/// # Safety
+///
+/// This function is unsafe because incorrect `flags` can cause undefined behaviour.
 #[inline]
 #[cfg(feature = "CL_VERSION_3_0")]
 pub unsafe fn create_image_with_properties(
@@ -535,6 +559,10 @@ pub fn get_pipe_info(pipe: cl_mem, param_name: cl_pipe_info) -> Result<InfoType,
 /// * `user_data` - passed as the user_data argument when pfn_notify is called.
 ///
 /// returns an empty Result or the error code from the OpenCL C API function.
+/// 
+/// # Safety
+///
+/// This function is unsafe because `user_data` must be valid.
 #[inline]
 pub unsafe fn set_mem_object_destructor_callback(
     memobj: cl_mem,
@@ -563,6 +591,10 @@ pub unsafe fn set_mem_object_destructor_callback(
 ///
 /// returns Result containing the address of the SVM buffer
 /// or the error code: CL_INVALID_VALUE if the address is NULL.
+/// 
+/// # Safety
+///
+/// This function is unsafe because `flags` must be valid.
 #[cfg(feature = "CL_VERSION_2_0")]
 #[inline]
 pub unsafe fn svm_alloc(
@@ -585,6 +617,10 @@ pub unsafe fn svm_alloc(
 ///
 /// * `context` - the valid OpenCL context used to create the SVM buffer.
 /// * `svm_pointer` - the value returned by a call to clSVMAlloc.
+///
+/// # Safety
+///
+/// This function is unsafe because `svm_pointer` is no longer valid after it is called.
 #[cfg(feature = "CL_VERSION_2_0")]
 #[inline]
 pub unsafe fn svm_free(context: cl_context, svm_pointer: *mut c_void) {

src/program.rs

@@ -127,6 +127,10 @@ pub fn create_program_with_source(
 ///
 /// returns a Result containing the new OpenCL program object
 /// or the error code from the OpenCL C API function.
+/// 
+/// # Safety
+///
+/// This is unsafe when a device is not a member of context.
 pub unsafe fn create_program_with_binary(
     context: cl_context,
     devices: &[cl_device_id],
@@ -163,6 +167,10 @@ pub unsafe fn create_program_with_binary(
 ///
 /// returns a Result containing the new OpenCL program object
 /// or the error code from the OpenCL C API function.
+/// 
+/// # Safety
+///
+/// This is unsafe when a device is not a member of context.
 #[cfg(feature = "CL_VERSION_1_2")]
 #[inline]
 pub unsafe fn create_program_with_builtin_kernels(
@@ -368,6 +376,10 @@ pub fn compile_program(
 /// # Panics
 ///
 /// Panics if `input_programs.is_empty()`.
+/// 
+/// # Safety
+///
+/// This is unsafe when a device is not a member of context.
 #[cfg(feature = "CL_VERSION_1_2")]
 #[inline]
 pub unsafe fn link_program(
@@ -408,6 +420,10 @@ pub unsafe fn link_program(
 /// * `user_data` - passed as an argument when pfn_notify is called, or ptr::null_mut().
 ///
 /// returns an empty Result or the error code from the OpenCL C API function.
+/// 
+/// # Safety
+///
+/// This function is unsafe because `user_data` must be valid.
 #[cfg(feature = "CL_VERSION_2_2")]
 #[inline]
 pub unsafe fn set_program_release_callback(
@@ -434,6 +450,10 @@ pub unsafe fn set_program_release_callback(
 /// of the specialization constant.
 ///
 /// returns an empty Result or the error code from the OpenCL C API function.
+/// 
+/// # Safety
+///
+/// This function is unsafe because `spec_size` and `spec_value` must be valid.
 #[cfg(feature = "CL_VERSION_2_2")]
 #[inline]
 pub unsafe fn set_program_specialization_constant(
@@ -457,6 +477,10 @@ pub unsafe fn set_program_specialization_constant(
 /// * `platform` - the platform.
 ///
 /// returns an empty Result or the error code from the OpenCL C API function.
+/// 
+/// # Safety
+///
+/// This function is unsafe because the platform compiler is not valid after this call.
 #[cfg(feature = "CL_VERSION_1_2")]
 #[inline]
 pub unsafe fn unload_platform_compiler(platform: cl_platform_id) -> Result<(), cl_int> {