From eddeb2ea2d43f33193f7cad2834dff75c5d3bc98 Mon Sep 17 00:00:00 2001 From: Vinzenz Schroeter Date: Sat, 7 Sep 2024 12:23:32 +0200 Subject: [PATCH] re-export everything from top-level for nicer docs --- crates/servicepoint_binding_c/README.md | 14 ++--- .../examples/lang_c/include/servicepoint.h | 17 +++--- crates/servicepoint_binding_c/src/bit_vec.rs | 2 +- .../src/brightness_grid.rs | 2 +- .../src/{c_slice.rs => byte_slice.rs} | 4 ++ crates/servicepoint_binding_c/src/command.rs | 19 +++--- .../servicepoint_binding_c/src/connection.rs | 2 +- .../servicepoint_binding_c/src/cp437_grid.rs | 10 ++-- crates/servicepoint_binding_c/src/lib.rs | 59 ++++++++++++++----- crates/servicepoint_binding_c/src/packet.rs | 2 +- .../servicepoint_binding_c/src/pixel_grid.rs | 2 +- crates/servicepoint_binding_cs/build.rs | 2 +- 12 files changed, 83 insertions(+), 52 deletions(-) rename crates/servicepoint_binding_c/src/{c_slice.rs => byte_slice.rs} (69%) diff --git a/crates/servicepoint_binding_c/README.md b/crates/servicepoint_binding_c/README.md index eacd65d..836af2e 100644 --- a/crates/servicepoint_binding_c/README.md +++ b/crates/servicepoint_binding_c/README.md @@ -17,18 +17,18 @@ This crate contains C bindings for the `servicepoint` library, enabling users to #include "servicepoint.h" int main(void) { - sp_Connection *connection = sp_connection_open("localhost:2342"); + SPConnection *connection = sp_connection_open("172.23.42.29:2342"); if (connection == NULL) return 1; - sp_PixelGrid *pixels = sp_pixel_grid_new(sp_PIXEL_WIDTH, sp_PIXEL_HEIGHT); + SPPixelGrid *pixels = sp_pixel_grid_new(SP_PIXEL_WIDTH, SP_PIXEL_HEIGHT); sp_pixel_grid_fill(pixels, true); - sp_Command *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); - sp_Packet *packet = sp_packet_from_command(command); - if (!sp_connection_send(connection, packet)) - return 1; + SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); + SPPacket *packet = sp_packet_from_command(command); + while (sp_connection_send(connection, sp_packet_clone(packet))); + sp_packet_dealloc(packet); sp_connection_dealloc(connection); return 0; } @@ -53,7 +53,7 @@ You have the choice of linking statically (recommended) or dynamically. ## Notes on differences to rust library - function names are: `sp_` \ \. -- Instances get consumed in the same way they do when writing rust / C# code. Do not use an instance after an (implicit!) free. +- Instances get consumed in the same way they do when writing rust code. Do not use an instance after an (implicit!) free. - Option or Result turn into nullable return values - check for NULL! - There are no specifics for C++ here yet. You might get a nicer header when generating directly for C++, but it should be usable. - Reading and writing to instances concurrently is not safe. Only reading concurrently is safe. diff --git a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h index 0a6069f..4b1cfda 100644 --- a/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h +++ b/crates/servicepoint_binding_c/examples/lang_c/include/servicepoint.h @@ -167,6 +167,8 @@ typedef struct SPPixelGrid SPPixelGrid; /** * Represents a span of memory (`&mut [u8]` ) as a struct usable by C code. * + * You should not create an instance of this type in your C code. + * * # Safety * * The caller has to make sure that: @@ -174,6 +176,8 @@ typedef struct SPPixelGrid SPPixelGrid; * - accesses to the memory pointed to with `start` is never accessed outside `length` * - the lifetime of the `CByteSlice` does not outlive the memory it points to, as described in * the function returning this type. + * - an instance of this created from C is never passed to a consuming function, as the rust code + * will try to free the memory of a potentially separate allocator. */ typedef struct SPByteSlice { /** @@ -186,11 +190,6 @@ typedef struct SPByteSlice { size_t length; } SPByteSlice; -/** - * Type alias for documenting the meaning of the variable in enum values - */ -typedef size_t SPOffset; - #ifdef __cplusplus extern "C" { #endif // __cplusplus @@ -556,7 +555,7 @@ size_t sp_brightness_grid_width(const struct SPBrightnessGrid *this_); * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct SPCommand *sp_command_bitmap_linear(SPOffset offset, +struct SPCommand *sp_command_bitmap_linear(size_t offset, struct SPBitVec *bit_vec, SPCompressionCode compression); @@ -581,7 +580,7 @@ struct SPCommand *sp_command_bitmap_linear(SPOffset offset, * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct SPCommand *sp_command_bitmap_linear_and(SPOffset offset, +struct SPCommand *sp_command_bitmap_linear_and(size_t offset, struct SPBitVec *bit_vec, SPCompressionCode compression); @@ -606,7 +605,7 @@ struct SPCommand *sp_command_bitmap_linear_and(SPOffset offset, * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct SPCommand *sp_command_bitmap_linear_or(SPOffset offset, +struct SPCommand *sp_command_bitmap_linear_or(size_t offset, struct SPBitVec *bit_vec, SPCompressionCode compression); @@ -652,7 +651,7 @@ struct SPCommand *sp_command_bitmap_linear_win(size_t x, * - the returned `Command` instance is freed in some way, either by using a consuming function or * by explicitly calling `sp_command_dealloc`. */ -struct SPCommand *sp_command_bitmap_linear_xor(SPOffset offset, +struct SPCommand *sp_command_bitmap_linear_xor(size_t offset, struct SPBitVec *bit_vec, SPCompressionCode compression); diff --git a/crates/servicepoint_binding_c/src/bit_vec.rs b/crates/servicepoint_binding_c/src/bit_vec.rs index d53792e..4455cfa 100644 --- a/crates/servicepoint_binding_c/src/bit_vec.rs +++ b/crates/servicepoint_binding_c/src/bit_vec.rs @@ -2,7 +2,7 @@ //! //! prefix `sp_bit_vec_` -use crate::c_slice::SPByteSlice; +use crate::SPByteSlice; use servicepoint::bitvec::prelude::{BitVec, Msb0}; /// A vector of bits diff --git a/crates/servicepoint_binding_c/src/brightness_grid.rs b/crates/servicepoint_binding_c/src/brightness_grid.rs index e4af777..a7d45f2 100644 --- a/crates/servicepoint_binding_c/src/brightness_grid.rs +++ b/crates/servicepoint_binding_c/src/brightness_grid.rs @@ -2,7 +2,7 @@ //! //! prefix `sp_brightness_grid_` -use crate::c_slice::SPByteSlice; +use crate::SPByteSlice; use servicepoint::{Brightness, DataRef, Grid, PrimitiveGrid}; use std::intrinsics::transmute; diff --git a/crates/servicepoint_binding_c/src/c_slice.rs b/crates/servicepoint_binding_c/src/byte_slice.rs similarity index 69% rename from crates/servicepoint_binding_c/src/c_slice.rs rename to crates/servicepoint_binding_c/src/byte_slice.rs index 9962511..fbdda2a 100644 --- a/crates/servicepoint_binding_c/src/c_slice.rs +++ b/crates/servicepoint_binding_c/src/byte_slice.rs @@ -3,6 +3,8 @@ #[repr(C)] /// Represents a span of memory (`&mut [u8]` ) as a struct usable by C code. /// +/// You should not create an instance of this type in your C code. +/// /// # Safety /// /// The caller has to make sure that: @@ -10,6 +12,8 @@ /// - accesses to the memory pointed to with `start` is never accessed outside `length` /// - the lifetime of the `CByteSlice` does not outlive the memory it points to, as described in /// the function returning this type. +/// - an instance of this created from C is never passed to a consuming function, as the rust code +/// will try to free the memory of a potentially separate allocator. pub struct SPByteSlice { /// The start address of the memory pub start: *mut u8, diff --git a/crates/servicepoint_binding_c/src/command.rs b/crates/servicepoint_binding_c/src/command.rs index 7c26536..3ece0f1 100644 --- a/crates/servicepoint_binding_c/src/command.rs +++ b/crates/servicepoint_binding_c/src/command.rs @@ -6,13 +6,10 @@ use std::ptr::null_mut; use servicepoint::{Brightness, Origin}; -use crate::bit_vec::SPBitVec; -use crate::brightness_grid::SPBrightnessGrid; -use crate::constants::SPCompressionCode; -use crate::cp437_grid::SPCp437Grid; -use crate::packet::SPPacket; -use crate::pixel_grid::SPPixelGrid; -use crate::SPOffset; +use crate::{ + SPBitVec, SPBrightnessGrid, SPCompressionCode, SPCp437Grid, SPPacket, + SPPixelGrid, +}; /// A low-level display command. /// @@ -196,7 +193,7 @@ pub unsafe extern "C" fn sp_command_char_brightness( /// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear( - offset: SPOffset, + offset: usize, bit_vec: *mut SPBitVec, compression: SPCompressionCode, ) -> *mut SPCommand { @@ -229,7 +226,7 @@ pub unsafe extern "C" fn sp_command_bitmap_linear( /// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_and( - offset: SPOffset, + offset: usize, bit_vec: *mut SPBitVec, compression: SPCompressionCode, ) -> *mut SPCommand { @@ -262,7 +259,7 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and( /// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_or( - offset: SPOffset, + offset: usize, bit_vec: *mut SPBitVec, compression: SPCompressionCode, ) -> *mut SPCommand { @@ -295,7 +292,7 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or( /// by explicitly calling `sp_command_dealloc`. #[no_mangle] pub unsafe extern "C" fn sp_command_bitmap_linear_xor( - offset: SPOffset, + offset: usize, bit_vec: *mut SPBitVec, compression: SPCompressionCode, ) -> *mut SPCommand { diff --git a/crates/servicepoint_binding_c/src/connection.rs b/crates/servicepoint_binding_c/src/connection.rs index e0556e3..ae82831 100644 --- a/crates/servicepoint_binding_c/src/connection.rs +++ b/crates/servicepoint_binding_c/src/connection.rs @@ -5,7 +5,7 @@ use std::ffi::{c_char, CStr}; use std::ptr::null_mut; -use crate::packet::SPPacket; +use crate::SPPacket; /// A connection to the display. /// diff --git a/crates/servicepoint_binding_c/src/cp437_grid.rs b/crates/servicepoint_binding_c/src/cp437_grid.rs index f181fdf..963456d 100644 --- a/crates/servicepoint_binding_c/src/cp437_grid.rs +++ b/crates/servicepoint_binding_c/src/cp437_grid.rs @@ -2,8 +2,8 @@ //! //! prefix `sp_cp437_grid_` -use crate::c_slice::SPByteSlice; -use servicepoint::{Cp437Grid, DataRef, Grid}; +use crate::SPByteSlice; +use servicepoint::{DataRef, Grid}; /// A C-wrapper for grid containing codepage 437 characters. /// @@ -18,7 +18,7 @@ use servicepoint::{Cp437Grid, DataRef, Grid}; /// sp_cp437_grid_dealloc(grid); /// ``` pub struct SPCp437Grid { - pub(crate) actual: Cp437Grid, + pub(crate) actual: servicepoint::Cp437Grid, } impl Clone for SPCp437Grid { @@ -45,7 +45,7 @@ pub unsafe extern "C" fn sp_cp437_grid_new( height: usize, ) -> *mut SPCp437Grid { Box::into_raw(Box::new(SPCp437Grid { - actual: Cp437Grid::new(width, height), + actual: servicepoint::Cp437Grid::new(width, height), })) } @@ -72,7 +72,7 @@ pub unsafe extern "C" fn sp_cp437_grid_load( ) -> *mut SPCp437Grid { let data = std::slice::from_raw_parts(data, data_length); Box::into_raw(Box::new(SPCp437Grid { - actual: Cp437Grid::load(width, height, data), + actual: servicepoint::Cp437Grid::load(width, height, data), })) } diff --git a/crates/servicepoint_binding_c/src/lib.rs b/crates/servicepoint_binding_c/src/lib.rs index c2d2877..fc60693 100644 --- a/crates/servicepoint_binding_c/src/lib.rs +++ b/crates/servicepoint_binding_c/src/lib.rs @@ -1,24 +1,55 @@ -//! C API wrapper for the `servicepoint` crate. +//! C API wrapper for the [servicepoint](https://docs.rs/servicepoint/latest/servicepoint/) crate. +//! +//! # Examples +//! +//! Make sure to check out [this GitHub repo](https://github.com/arfst23/ServicePoint) as well! +//! +//! ```C +//! #include +//! #include "servicepoint.h" +//! +//! int main(void) { +//! SPConnection *connection = sp_connection_open("172.23.42.29:2342"); +//! if (connection == NULL) +//! return 1; +//! +//! SPPixelGrid *pixels = sp_pixel_grid_new(SP_PIXEL_WIDTH, SP_PIXEL_HEIGHT); +//! sp_pixel_grid_fill(pixels, true); +//! +//! SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed); +//! SPPacket *packet = sp_packet_from_command(command); +//! while (sp_connection_send(connection, sp_packet_clone(packet))); +//! +//! sp_packet_dealloc(packet); +//! sp_connection_dealloc(connection); +//! return 0; +//! } +//! ``` -pub use crate::c_slice::SPByteSlice; +pub use bit_vec::*; +pub use brightness_grid::*; +pub use byte_slice::*; +pub use command::*; +pub use connection::*; +pub use constants::*; +pub use cp437_grid::*; +pub use packet::*; +pub use pixel_grid::*; -pub mod bit_vec; +mod bit_vec; -pub mod brightness_grid; +mod brightness_grid; -pub mod command; +mod command; -pub mod connection; +mod connection; -pub mod packet; +mod packet; -pub mod pixel_grid; +mod pixel_grid; -pub mod c_slice; +mod byte_slice; -pub mod cp437_grid; +mod cp437_grid; -pub mod constants; - -/// Type alias for documenting the meaning of the variable in enum values -pub type SPOffset = usize; +mod constants; diff --git a/crates/servicepoint_binding_c/src/packet.rs b/crates/servicepoint_binding_c/src/packet.rs index c3304b8..c575de7 100644 --- a/crates/servicepoint_binding_c/src/packet.rs +++ b/crates/servicepoint_binding_c/src/packet.rs @@ -4,7 +4,7 @@ use std::ptr::null_mut; -use crate::command::SPCommand; +use crate::SPCommand; /// The raw packet pub struct SPPacket(pub(crate) servicepoint::Packet); diff --git a/crates/servicepoint_binding_c/src/pixel_grid.rs b/crates/servicepoint_binding_c/src/pixel_grid.rs index 585fda3..d8b4a32 100644 --- a/crates/servicepoint_binding_c/src/pixel_grid.rs +++ b/crates/servicepoint_binding_c/src/pixel_grid.rs @@ -4,7 +4,7 @@ use servicepoint::{DataRef, Grid}; -use crate::c_slice::SPByteSlice; +use crate::byte_slice::SPByteSlice; /// A grid of pixels. /// diff --git a/crates/servicepoint_binding_cs/build.rs b/crates/servicepoint_binding_cs/build.rs index a74e7ff..e8fe1f5 100644 --- a/crates/servicepoint_binding_cs/build.rs +++ b/crates/servicepoint_binding_cs/build.rs @@ -11,7 +11,7 @@ fn main() { .input_extern_file("../servicepoint_binding_c/src/connection.rs") .input_extern_file("../servicepoint_binding_c/src/pixel_grid.rs") .input_extern_file("../servicepoint_binding_c/src/lib.rs") - .input_extern_file("../servicepoint_binding_c/src/c_slice.rs") + .input_extern_file("../servicepoint_binding_c/src/byte_slice.rs") .input_extern_file("../servicepoint_binding_c/src/packet.rs") .input_extern_file("../servicepoint_binding_c/src/constants.rs") .csharp_dll_name("servicepoint_binding_c")