From 8414b0140387fad002d7200a15ebf8432bb22172 Mon Sep 17 00:00:00 2001
From: yanchith <yanchi.toth@gmail.com>
Date: Fri, 17 Jan 2020 15:04:57 +0100
Subject: [PATCH] Add # Safety docs to wgpu-remote

Only two unsafe functions were used internally:

- `slice::from_raw_parts`
- `Box::from_raw`

The safety messages are adapted from the safety messages of these functions.
---
 wgpu-remote/src/lib.rs    | 13 +++++++++++++
 wgpu-remote/src/server.rs | 31 +++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+)

diff --git a/wgpu-remote/src/lib.rs b/wgpu-remote/src/lib.rs
index a684a66a6f..693c504d4e 100644
--- a/wgpu-remote/src/lib.rs
+++ b/wgpu-remote/src/lib.rs
@@ -70,12 +70,21 @@ pub extern "C" fn wgpu_client_new() -> Infrastructure {
     }
 }
 
+/// # Safety
+///
+/// This function is unsafe because improper use may lead to memory
+/// problems. For example, a double-free may occur if the function is called
+/// twice on the same raw pointer.
 #[no_mangle]
 pub unsafe extern "C" fn wgpu_client_delete(client: *mut Client) {
     log::info!("Terminating WGPU client");
     let _client = Box::from_raw(client);
 }
 
+/// # Safety
+///
+/// This function is unsafe as there is no guarantee that the given pointer is
+/// valid for `id_length` elements.
 #[no_mangle]
 pub unsafe extern "C" fn wgpu_client_make_adapter_ids(
     client: &Client,
@@ -100,6 +109,10 @@ pub unsafe extern "C" fn wgpu_client_make_adapter_ids(
     id_length - ids.len()
 }
 
+/// # Safety
+///
+/// This function is unsafe as there is no guarantee that the given pointer is
+/// valid for `id_length` elements.
 #[no_mangle]
 pub unsafe extern "C" fn wgpu_client_kill_adapter_ids(
     client: &Client,
diff --git a/wgpu-remote/src/server.rs b/wgpu-remote/src/server.rs
index 7e7327f87c..ccabb93b87 100644
--- a/wgpu-remote/src/server.rs
+++ b/wgpu-remote/src/server.rs
@@ -14,6 +14,11 @@ pub extern "C" fn wgpu_server_new() -> *mut Global {
     Box::into_raw(Box::new(Global::new("wgpu")))
 }
 
+/// # Safety
+///
+/// This function is unsafe because improper use may lead to memory
+/// problems. For example, a double-free may occur if the function is called
+/// twice on the same raw pointer.
 #[no_mangle]
 pub unsafe extern "C" fn wgpu_server_delete(global: *mut Global) {
     log::info!("Terminating WGPU server");
@@ -25,6 +30,11 @@ pub unsafe extern "C" fn wgpu_server_delete(global: *mut Global) {
 /// Provide the list of IDs to pick from.
 ///
 /// Returns the index in this list, or -1 if unable to pick.
+///
+/// # Safety
+///
+/// This function is unsafe as there is no guarantee that the given pointer is
+/// valid for `id_length` elements.
 #[no_mangle]
 pub unsafe extern "C" fn wgpu_server_instance_request_adapter(
     global: &Global,
@@ -67,6 +77,10 @@ pub extern "C" fn wgpu_server_device_create_buffer(
     gfx_select!(self_id => global.device_create_buffer(self_id, desc, new_id));
 }
 
+/// # Safety
+///
+/// This function is unsafe as there is no guarantee that the given pointer is
+/// valid for `size` elements.
 #[no_mangle]
 pub unsafe extern "C" fn wgpu_server_device_set_buffer_sub_data(
     global: &Global,
@@ -80,6 +94,10 @@ pub unsafe extern "C" fn wgpu_server_device_set_buffer_sub_data(
     gfx_select!(self_id => global.device_set_buffer_sub_data(self_id, buffer_id, offset, slice));
 }
 
+/// # Safety
+///
+/// This function is unsafe as there is no guarantee that the given pointer is
+/// valid for `size` elements.
 #[no_mangle]
 pub unsafe extern "C" fn wgpu_server_device_get_buffer_sub_data(
     global: &Global,
@@ -118,6 +136,10 @@ pub extern "C" fn wgpu_server_encoder_destroy(
     gfx_select!(self_id => global.command_encoder_destroy(self_id));
 }
 
+/// # Safety
+///
+/// This function is unsafe as there is no guarantee that the given pointer is
+/// valid for `byte_length` elements.
 #[no_mangle]
 pub unsafe extern "C" fn wgpu_server_encode_compute_pass(
     global: &Global,
@@ -129,6 +151,11 @@ pub unsafe extern "C" fn wgpu_server_encode_compute_pass(
     gfx_select!(self_id => global.command_encoder_run_compute_pass(self_id, raw_data));
 }
 
+/// # Safety
+///
+/// This function is unsafe as there is no guarantee that the given pointers are
+/// valid for `color_attachments_length` and `command_length` elements,
+/// respectively.
 #[no_mangle]
 pub unsafe extern "C" fn wgpu_server_encode_render_pass(
     global: &Global,
@@ -144,6 +171,10 @@ pub unsafe extern "C" fn wgpu_server_encode_render_pass(
     gfx_select!(self_id => global.command_encoder_run_render_pass(self_id, color_attachments, depth_stencil_attachment, raw_pass));
 }
 
+/// # Safety
+///
+/// This function is unsafe as there is no guarantee that the given pointer is
+/// valid for `command_buffer_id_length` elements.
 #[no_mangle]
 pub unsafe extern "C" fn wgpu_server_queue_submit(
     global: &Global,