1 // This file is Copyright its original authors, visible in version control
4 // This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE>
5 // or the MIT license <LICENSE-MIT>, at your option.
6 // You may not use this file except in accordance with one or both of these
9 //! Printing logic for basic blocks of Rust-mapped code - parts of functions and declarations but
10 //! not the full mapping logic.
15 use proc_macro2::TokenTree;
16 use quote::format_ident;
20 /// Writes out a C++ wrapper class for the given type, which contains various utilities to access
21 /// the underlying C-mapped type safely avoiding some common memory management issues by handling
22 /// resource-freeing and prevending accidental raw copies.
23 pub fn write_cpp_wrapper(cpp_header_file: &mut File, ty: &str, has_destructor: bool, trait_methods: Option<Vec<(String, String)>>) {
24 writeln!(cpp_header_file, "class {} {{", ty).unwrap();
25 writeln!(cpp_header_file, "private:").unwrap();
26 writeln!(cpp_header_file, "\tLDK{} self;", ty).unwrap();
27 writeln!(cpp_header_file, "public:").unwrap();
28 writeln!(cpp_header_file, "\t{}(const {}&) = delete;", ty, ty).unwrap();
29 writeln!(cpp_header_file, "\t{}({}&& o) : self(o.self) {{ memset(&o, 0, sizeof({})); }}", ty, ty, ty).unwrap();
30 writeln!(cpp_header_file, "\t{}(LDK{}&& m_self) : self(m_self) {{ memset(&m_self, 0, sizeof(LDK{})); }}", ty, ty, ty).unwrap();
31 writeln!(cpp_header_file, "\toperator LDK{}() && {{ LDK{} res = self; memset(&self, 0, sizeof(LDK{})); return res; }}", ty, ty, ty).unwrap();
33 writeln!(cpp_header_file, "\t~{}() {{ {}_free(self); }}", ty, ty).unwrap();
34 writeln!(cpp_header_file, "\t{}& operator=({}&& o) {{ {}_free(self); self = o.self; memset(&o, 0, sizeof({})); return *this; }}", ty, ty, ty, ty).unwrap();
36 writeln!(cpp_header_file, "\t{}& operator=({}&& o) {{ self = o.self; memset(&o, 0, sizeof({})); return *this; }}", ty, ty, ty).unwrap();
38 writeln!(cpp_header_file, "\tLDK{}* operator &() {{ return &self; }}", ty).unwrap();
39 writeln!(cpp_header_file, "\tLDK{}* operator ->() {{ return &self; }}", ty).unwrap();
40 writeln!(cpp_header_file, "\tconst LDK{}* operator &() const {{ return &self; }}", ty).unwrap();
41 writeln!(cpp_header_file, "\tconst LDK{}* operator ->() const {{ return &self; }}", ty).unwrap();
42 if let Some(methods) = trait_methods {
43 for (meth_name, meth_docs) in methods {
44 cpp_header_file.write_all(meth_docs.as_bytes()).unwrap();
45 // Note that we have zero logic to print C/C__ code for a given function. Instead, we
46 // simply use sed to replace the following in genbindings.sh
47 writeln!(cpp_header_file, "XXX {} {}", ty, meth_name).unwrap();
50 writeln!(cpp_header_file, "}};").unwrap();
53 /// Writes out a C-callable concrete Result<A, B> struct and utility methods
54 pub fn write_result_block<W: std::io::Write>(w: &mut W, mangled_container: &str, ok_type: &str, err_type: &str, clonable: bool) {
55 writeln!(w, "#[repr(C)]").unwrap();
56 writeln!(w, "/// The contents of {}", mangled_container).unwrap();
57 writeln!(w, "pub union {}Ptr {{", mangled_container).unwrap();
59 writeln!(w, "\t/// A pointer to the contents in the success state.").unwrap();
60 writeln!(w, "\t/// Reading from this pointer when `result_ok` is not set is undefined.").unwrap();
61 writeln!(w, "\tpub result: *mut {},", ok_type).unwrap();
63 writeln!(w, "\t/// Note that this value is always NULL, as there are no contents in the OK variant").unwrap();
64 writeln!(w, "\tpub result: *mut core::ffi::c_void,").unwrap();
67 writeln!(w, "\t/// A pointer to the contents in the error state.").unwrap();
68 writeln!(w, "\t/// Reading from this pointer when `result_ok` is set is undefined.").unwrap();
69 writeln!(w, "\tpub err: *mut {},", err_type).unwrap();
71 writeln!(w, "\t/// Note that this value is always NULL, as there are no contents in the Err variant").unwrap();
72 writeln!(w, "\tpub err: *mut core::ffi::c_void,").unwrap();
74 writeln!(w, "}}").unwrap();
75 writeln!(w, "#[repr(C)]").unwrap();
76 writeln!(w, "/// A {} represents the result of a fallible operation,", mangled_container).unwrap();
77 writeln!(w, "/// containing a {} on success and a {} on failure.", ok_type, err_type).unwrap();
78 writeln!(w, "/// `result_ok` indicates the overall state, and the contents are provided via `contents`.").unwrap();
79 writeln!(w, "pub struct {} {{", mangled_container).unwrap();
80 writeln!(w, "\t/// The contents of this {}, accessible via either", mangled_container).unwrap();
81 writeln!(w, "\t/// `err` or `result` depending on the state of `result_ok`.").unwrap();
82 writeln!(w, "\tpub contents: {}Ptr,", mangled_container).unwrap();
83 writeln!(w, "\t/// Whether this {} represents a success state.", mangled_container).unwrap();
84 writeln!(w, "\tpub result_ok: bool,").unwrap();
85 writeln!(w, "}}").unwrap();
87 writeln!(w, "#[no_mangle]").unwrap();
89 writeln!(w, "/// Creates a new {} in the success state.", mangled_container).unwrap();
90 writeln!(w, "pub extern \"C\" fn {}_ok(o: {}) -> {} {{", mangled_container, ok_type, mangled_container).unwrap();
92 writeln!(w, "/// Creates a new {} in the success state.", mangled_container).unwrap();
93 writeln!(w, "pub extern \"C\" fn {}_ok() -> {} {{", mangled_container, mangled_container).unwrap();
95 writeln!(w, "\t{} {{", mangled_container).unwrap();
96 writeln!(w, "\t\tcontents: {}Ptr {{", mangled_container).unwrap();
98 writeln!(w, "\t\t\tresult: Box::into_raw(Box::new(o)),").unwrap();
100 writeln!(w, "\t\t\tresult: core::ptr::null_mut(),").unwrap();
102 writeln!(w, "\t\t}},").unwrap();
103 writeln!(w, "\t\tresult_ok: true,").unwrap();
104 writeln!(w, "\t}}").unwrap();
105 writeln!(w, "}}").unwrap();
107 writeln!(w, "#[no_mangle]").unwrap();
108 if err_type != "()" {
109 writeln!(w, "/// Creates a new {} in the error state.", mangled_container).unwrap();
110 writeln!(w, "pub extern \"C\" fn {}_err(e: {}) -> {} {{", mangled_container, err_type, mangled_container).unwrap();
112 writeln!(w, "/// Creates a new {} in the error state.", mangled_container).unwrap();
113 writeln!(w, "pub extern \"C\" fn {}_err() -> {} {{", mangled_container, mangled_container).unwrap();
115 writeln!(w, "\t{} {{", mangled_container).unwrap();
116 writeln!(w, "\t\tcontents: {}Ptr {{", mangled_container).unwrap();
117 if err_type != "()" {
118 writeln!(w, "\t\t\terr: Box::into_raw(Box::new(e)),").unwrap();
120 writeln!(w, "\t\t\terr: core::ptr::null_mut(),").unwrap();
122 writeln!(w, "\t\t}},").unwrap();
123 writeln!(w, "\t\tresult_ok: false,").unwrap();
124 writeln!(w, "\t}}").unwrap();
125 writeln!(w, "}}").unwrap();
127 writeln!(w, "/// Checks if the given object is currently in the success state").unwrap();
128 writeln!(w, "#[no_mangle]").unwrap();
129 writeln!(w, "pub extern \"C\" fn {}_is_ok(o: &{}) -> bool {{", mangled_container, mangled_container).unwrap();
130 writeln!(w, "\to.result_ok").unwrap();
131 writeln!(w, "}}").unwrap();
133 writeln!(w, "#[no_mangle]").unwrap();
134 writeln!(w, "/// Frees any resources used by the {}.", mangled_container).unwrap();
135 writeln!(w, "pub extern \"C\" fn {}_free(_res: {}) {{ }}", mangled_container, mangled_container).unwrap();
136 writeln!(w, "impl Drop for {} {{", mangled_container).unwrap();
137 writeln!(w, "\tfn drop(&mut self) {{").unwrap();
138 writeln!(w, "\t\tif self.result_ok {{").unwrap();
140 writeln!(w, "\t\t\tif unsafe {{ !(self.contents.result as *mut ()).is_null() }} {{").unwrap();
141 writeln!(w, "\t\t\t\tlet _ = unsafe {{ Box::from_raw(self.contents.result) }};").unwrap();
142 writeln!(w, "\t\t\t}}").unwrap();
144 writeln!(w, "\t\t}} else {{").unwrap();
145 if err_type != "()" {
146 writeln!(w, "\t\t\tif unsafe {{ !(self.contents.err as *mut ()).is_null() }} {{").unwrap();
147 writeln!(w, "\t\t\t\tlet _ = unsafe {{ Box::from_raw(self.contents.err) }};").unwrap();
148 writeln!(w, "\t\t\t}}").unwrap();
150 writeln!(w, "\t\t}}").unwrap();
151 writeln!(w, "\t}}").unwrap();
152 writeln!(w, "}}").unwrap();
154 writeln!(w, "impl From<crate::c_types::CResultTempl<{}, {}>> for {} {{", ok_type, err_type, mangled_container).unwrap();
155 writeln!(w, "\tfn from(mut o: crate::c_types::CResultTempl<{}, {}>) -> Self {{", ok_type, err_type).unwrap();
156 writeln!(w, "\t\tlet contents = if o.result_ok {{").unwrap();
158 writeln!(w, "\t\t\tlet result = unsafe {{ o.contents.result }};").unwrap();
159 writeln!(w, "\t\t\tunsafe {{ o.contents.result = core::ptr::null_mut() }};").unwrap();
160 writeln!(w, "\t\t\t{}Ptr {{ result }}", mangled_container).unwrap();
162 writeln!(w, "\t\t\tlet _ = unsafe {{ Box::from_raw(o.contents.result) }};").unwrap();
163 writeln!(w, "\t\t\to.contents.result = core::ptr::null_mut();").unwrap();
164 writeln!(w, "\t\t\t{}Ptr {{ result: core::ptr::null_mut() }}", mangled_container).unwrap();
166 writeln!(w, "\t\t}} else {{").unwrap();
167 if err_type != "()" {
168 writeln!(w, "\t\t\tlet err = unsafe {{ o.contents.err }};").unwrap();
169 writeln!(w, "\t\t\tunsafe {{ o.contents.err = core::ptr::null_mut(); }}").unwrap();
170 writeln!(w, "\t\t\t{}Ptr {{ err }}", mangled_container).unwrap();
172 writeln!(w, "\t\t\tlet _ = unsafe {{ Box::from_raw(o.contents.err) }};").unwrap();
173 writeln!(w, "\t\t\to.contents.err = core::ptr::null_mut();").unwrap();
174 writeln!(w, "\t\t\t{}Ptr {{ err: core::ptr::null_mut() }}", mangled_container).unwrap();
176 writeln!(w, "\t\t}};").unwrap();
177 writeln!(w, "\t\tSelf {{").unwrap();
178 writeln!(w, "\t\t\tcontents,").unwrap();
179 writeln!(w, "\t\t\tresult_ok: o.result_ok,").unwrap();
180 writeln!(w, "\t\t}}").unwrap();
181 writeln!(w, "\t}}").unwrap();
182 writeln!(w, "}}").unwrap();
185 writeln!(w, "impl Clone for {} {{", mangled_container).unwrap();
186 writeln!(w, "\tfn clone(&self) -> Self {{").unwrap();
187 writeln!(w, "\t\tif self.result_ok {{").unwrap();
188 writeln!(w, "\t\t\tSelf {{ result_ok: true, contents: {}Ptr {{", mangled_container).unwrap();
190 writeln!(w, "\t\t\t\tresult: Box::into_raw(Box::new(<{}>::clone(unsafe {{ &*self.contents.result }})))", ok_type).unwrap();
192 writeln!(w, "\t\t\t\tresult: core::ptr::null_mut()").unwrap();
194 writeln!(w, "\t\t\t}} }}").unwrap();
195 writeln!(w, "\t\t}} else {{").unwrap();
196 writeln!(w, "\t\t\tSelf {{ result_ok: false, contents: {}Ptr {{", mangled_container).unwrap();
197 if err_type != "()" {
198 writeln!(w, "\t\t\t\terr: Box::into_raw(Box::new(<{}>::clone(unsafe {{ &*self.contents.err }})))", err_type).unwrap();
200 writeln!(w, "\t\t\t\terr: core::ptr::null_mut()").unwrap();
202 writeln!(w, "\t\t\t}} }}").unwrap();
203 writeln!(w, "\t\t}}").unwrap();
204 writeln!(w, "\t}}").unwrap();
205 writeln!(w, "}}").unwrap();
206 writeln!(w, "#[no_mangle]").unwrap();
207 writeln!(w, "/// Creates a new {} which has the same data as `orig`", mangled_container).unwrap();
208 writeln!(w, "/// but with all dynamically-allocated buffers duplicated in new buffers.").unwrap();
209 writeln!(w, "pub extern \"C\" fn {}_clone(orig: &{}) -> {} {{ Clone::clone(&orig) }}", mangled_container, mangled_container, mangled_container).unwrap();
213 /// Writes out a C-callable concrete Vec<A> struct and utility methods
214 pub fn write_vec_block<W: std::io::Write>(w: &mut W, mangled_container: &str, inner_type: &str, clonable: bool) {
215 writeln!(w, "#[repr(C)]").unwrap();
216 writeln!(w, "/// A dynamically-allocated array of {}s of arbitrary size.", inner_type).unwrap();
217 writeln!(w, "/// This corresponds to std::vector in C++").unwrap();
218 writeln!(w, "pub struct {} {{", mangled_container).unwrap();
219 writeln!(w, "\t/// The elements in the array.").unwrap();
220 writeln!(w, "\t/// If datalen is non-0 this must be a valid, non-NULL pointer allocated by malloc().").unwrap();
221 writeln!(w, "\tpub data: *mut {},", inner_type).unwrap();
222 writeln!(w, "\t/// The number of elements pointed to by `data`.").unwrap();
223 writeln!(w, "\tpub datalen: usize").unwrap();
224 writeln!(w, "}}").unwrap();
226 writeln!(w, "impl {} {{", mangled_container).unwrap();
227 writeln!(w, "\t#[allow(unused)] pub(crate) fn into_rust(&mut self) -> Vec<{}> {{", inner_type).unwrap();
228 writeln!(w, "\t\tif self.datalen == 0 {{ return Vec::new(); }}").unwrap();
229 writeln!(w, "\t\tlet ret = unsafe {{ Box::from_raw(core::slice::from_raw_parts_mut(self.data, self.datalen)) }}.into();").unwrap();
230 writeln!(w, "\t\tself.data = core::ptr::null_mut();").unwrap();
231 writeln!(w, "\t\tself.datalen = 0;").unwrap();
232 writeln!(w, "\t\tret").unwrap();
233 writeln!(w, "\t}}").unwrap();
234 writeln!(w, "\t#[allow(unused)] pub(crate) fn as_slice(&self) -> &[{}] {{", inner_type).unwrap();
235 writeln!(w, "\t\tunsafe {{ core::slice::from_raw_parts_mut(self.data, self.datalen) }}").unwrap();
236 writeln!(w, "\t}}").unwrap();
237 writeln!(w, "}}").unwrap();
239 writeln!(w, "impl From<Vec<{}>> for {} {{", inner_type, mangled_container).unwrap();
240 writeln!(w, "\tfn from(v: Vec<{}>) -> Self {{", inner_type).unwrap();
241 writeln!(w, "\t\tlet datalen = v.len();").unwrap();
242 writeln!(w, "\t\tlet data = Box::into_raw(v.into_boxed_slice());").unwrap();
243 writeln!(w, "\t\tSelf {{ datalen, data: unsafe {{ (*data).as_mut_ptr() }} }}").unwrap();
244 writeln!(w, "\t}}").unwrap();
245 writeln!(w, "}}").unwrap();
247 writeln!(w, "#[no_mangle]").unwrap();
248 writeln!(w, "/// Frees the buffer pointed to by `data` if `datalen` is non-0.").unwrap();
249 writeln!(w, "pub extern \"C\" fn {}_free(_res: {}) {{ }}", mangled_container, mangled_container).unwrap();
250 writeln!(w, "impl Drop for {} {{", mangled_container).unwrap();
251 writeln!(w, "\tfn drop(&mut self) {{").unwrap();
252 writeln!(w, "\t\tif self.datalen == 0 {{ return; }}").unwrap();
253 writeln!(w, "\t\tlet _ = unsafe {{ Box::from_raw(core::slice::from_raw_parts_mut(self.data, self.datalen)) }};").unwrap();
254 writeln!(w, "\t}}").unwrap();
255 writeln!(w, "}}").unwrap();
257 writeln!(w, "impl Clone for {} {{", mangled_container).unwrap();
258 writeln!(w, "\tfn clone(&self) -> Self {{").unwrap();
259 writeln!(w, "\t\tlet mut res = Vec::new();").unwrap();
260 writeln!(w, "\t\tif self.datalen == 0 {{ return Self::from(res); }}").unwrap();
261 writeln!(w, "\t\tres.extend_from_slice(unsafe {{ core::slice::from_raw_parts_mut(self.data, self.datalen) }});").unwrap();
262 writeln!(w, "\t\tSelf::from(res)").unwrap();
263 writeln!(w, "\t}}").unwrap();
264 writeln!(w, "}}").unwrap();
268 /// Writes out a C-callable concrete (A, B, ...) struct and utility methods
269 pub fn write_tuple_block<W: std::io::Write>(w: &mut W, mangled_container: &str, types: &[String], clonable: bool) {
270 writeln!(w, "#[repr(C)]").unwrap();
271 writeln!(w, "/// A tuple of {} elements. See the individual fields for the types contained.", types.len()).unwrap();
272 writeln!(w, "pub struct {} {{", mangled_container).unwrap();
273 for (idx, ty) in types.iter().enumerate() {
274 writeln!(w, "\t/// The element at position {}", idx).unwrap();
275 writeln!(w, "\tpub {}: {},", ('a' as u8 + idx as u8) as char, ty).unwrap();
277 writeln!(w, "}}").unwrap();
279 let mut tuple_str = "(".to_owned();
280 for (idx, ty) in types.iter().enumerate() {
281 if idx != 0 { tuple_str += ", "; }
286 writeln!(w, "impl From<{}> for {} {{", tuple_str, mangled_container).unwrap();
287 writeln!(w, "\tfn from (tup: {}) -> Self {{", tuple_str).unwrap();
288 writeln!(w, "\t\tSelf {{").unwrap();
289 for idx in 0..types.len() {
290 writeln!(w, "\t\t\t{}: tup.{},", ('a' as u8 + idx as u8) as char, idx).unwrap();
292 writeln!(w, "\t\t}}").unwrap();
293 writeln!(w, "\t}}").unwrap();
294 writeln!(w, "}}").unwrap();
295 writeln!(w, "impl {} {{", mangled_container).unwrap();
296 writeln!(w, "\t#[allow(unused)] pub(crate) fn to_rust(mut self) -> {} {{", tuple_str).unwrap();
297 write!(w, "\t\t(").unwrap();
298 for idx in 0..types.len() {
299 write!(w, "{}self.{}", if idx != 0 {", "} else {""}, ('a' as u8 + idx as u8) as char).unwrap();
301 writeln!(w, ")").unwrap();
302 writeln!(w, "\t}}").unwrap();
303 writeln!(w, "}}").unwrap();
306 writeln!(w, "impl Clone for {} {{", mangled_container).unwrap();
307 writeln!(w, "\tfn clone(&self) -> Self {{").unwrap();
308 writeln!(w, "\t\tSelf {{").unwrap();
309 for idx in 0..types.len() {
310 writeln!(w, "\t\t\t{}: Clone::clone(&self.{}),", ('a' as u8 + idx as u8) as char, ('a' as u8 + idx as u8) as char).unwrap();
312 writeln!(w, "\t\t}}").unwrap();
313 writeln!(w, "\t}}").unwrap();
314 writeln!(w, "}}").unwrap();
315 writeln!(w, "#[no_mangle]").unwrap();
316 writeln!(w, "/// Creates a new tuple which has the same data as `orig`").unwrap();
317 writeln!(w, "/// but with all dynamically-allocated buffers duplicated in new buffers.").unwrap();
318 writeln!(w, "pub extern \"C\" fn {}_clone(orig: &{}) -> {} {{ Clone::clone(&orig) }}", mangled_container, mangled_container, mangled_container).unwrap();
321 writeln!(w, "/// Creates a new {} from the contained elements.", mangled_container).unwrap();
322 write!(w, "#[no_mangle]\npub extern \"C\" fn {}_new(", mangled_container).unwrap();
323 for (idx, gen) in types.iter().enumerate() {
324 write!(w, "{}{}: ", if idx != 0 { ", " } else { "" }, ('a' as u8 + idx as u8) as char).unwrap();
325 //if !self.write_c_type_intern(&mut created_container, gen, generics, false, false, false) { return false; }
326 write!(w, "{}", gen).unwrap();
328 writeln!(w, ") -> {} {{", mangled_container).unwrap();
329 write!(w, "\t{} {{ ", mangled_container).unwrap();
330 for idx in 0..types.len() {
331 write!(w, "{}, ", ('a' as u8 + idx as u8) as char).unwrap();
333 writeln!(w, "}}\n}}\n").unwrap();
335 writeln!(w, "#[no_mangle]").unwrap();
336 writeln!(w, "/// Frees any resources used by the {}.", mangled_container).unwrap();
337 writeln!(w, "pub extern \"C\" fn {}_free(_res: {}) {{ }}", mangled_container, mangled_container).unwrap();
340 /// Writes out a C-callable concrete Option<A> struct and utility methods
341 pub fn write_option_block<W: std::io::Write>(w: &mut W, mangled_container: &str, inner_type: &str, clonable: bool) {
342 writeln!(w, "#[repr(C)]").unwrap();
344 writeln!(w, "#[derive(Clone)]").unwrap();
346 writeln!(w, "/// An enum which can either contain a {} or not", inner_type).unwrap();
347 writeln!(w, "pub enum {} {{", mangled_container).unwrap();
348 writeln!(w, "\t/// When we're in this state, this {} contains a {}", mangled_container, inner_type).unwrap();
349 if inner_type != "" {
350 writeln!(w, "\tSome({}),", inner_type).unwrap();
352 writeln!(w, "\tSome,").unwrap();
354 writeln!(w, "\t/// When we're in this state, this {} contains nothing", mangled_container).unwrap();
355 writeln!(w, "\tNone").unwrap();
356 writeln!(w, "}}").unwrap();
358 writeln!(w, "impl {} {{", mangled_container).unwrap();
359 writeln!(w, "\t#[allow(unused)] pub(crate) fn is_some(&self) -> bool {{").unwrap();
360 writeln!(w, "\t\tif let Self::None = self {{ false }} else {{ true }}").unwrap();
361 writeln!(w, "\t}}").unwrap();
362 writeln!(w, "\t#[allow(unused)] pub(crate) fn is_none(&self) -> bool {{").unwrap();
363 writeln!(w, "\t\t!self.is_some()").unwrap();
364 writeln!(w, "\t}}").unwrap();
365 if inner_type != "" {
366 writeln!(w, "\t#[allow(unused)] pub(crate) fn take(mut self) -> {} {{", inner_type).unwrap();
367 writeln!(w, "\t\tif let Self::Some(v) = self {{ v }} else {{ unreachable!() }}").unwrap();
368 writeln!(w, "\t}}").unwrap();
370 writeln!(w, "}}").unwrap();
372 writeln!(w, "#[no_mangle]").unwrap();
373 writeln!(w, "/// Constructs a new {} containing a {}", mangled_container, inner_type).unwrap();
374 if inner_type != "" {
375 writeln!(w, "pub extern \"C\" fn {}_some(o: {}) -> {} {{", mangled_container, inner_type, mangled_container).unwrap();
376 writeln!(w, "\t{}::Some(o)", mangled_container).unwrap();
378 writeln!(w, "pub extern \"C\" fn {}_some() -> {} {{", mangled_container, mangled_container).unwrap();
379 writeln!(w, "\t{}::Some", mangled_container).unwrap();
381 writeln!(w, "}}").unwrap();
383 writeln!(w, "#[no_mangle]").unwrap();
384 writeln!(w, "/// Constructs a new {} containing nothing", mangled_container).unwrap();
385 writeln!(w, "pub extern \"C\" fn {}_none() -> {} {{", mangled_container, mangled_container).unwrap();
386 writeln!(w, "\t{}::None", mangled_container).unwrap();
387 writeln!(w, "}}").unwrap();
389 writeln!(w, "#[no_mangle]").unwrap();
390 writeln!(w, "/// Frees any resources associated with the {}, if we are in the Some state", inner_type).unwrap();
391 writeln!(w, "pub extern \"C\" fn {}_free(_res: {}) {{ }}", mangled_container, mangled_container).unwrap();
393 writeln!(w, "#[no_mangle]").unwrap();
394 writeln!(w, "/// Creates a new {} which has the same data as `orig`", mangled_container).unwrap();
395 writeln!(w, "/// but with all dynamically-allocated buffers duplicated in new buffers.").unwrap();
396 writeln!(w, "pub extern \"C\" fn {}_clone(orig: &{}) -> {} {{ Clone::clone(&orig) }}", mangled_container, mangled_container, mangled_container).unwrap();
400 /// Prints the docs from a given attribute list unless its tagged no export
401 pub fn writeln_fn_docs<'a, W: std::io::Write, I>(w: &mut W, attrs: &[syn::Attribute], prefix: &str, types: &mut TypeResolver, generics: Option<&GenericTypes>, args: I, ret: &syn::ReturnType) where I: Iterator<Item = &'a syn::FnArg> {
402 writeln_docs_impl(w, attrs, prefix, Some((types, generics,
403 args.filter_map(|arg| if let syn::FnArg::Typed(ty) = arg {
404 if let syn::Pat::Ident(id) = &*ty.pat {
405 Some((id.ident.to_string(), &*ty.ty))
406 } else { unimplemented!() }
408 if let syn::ReturnType::Type(_, ty) = ret { Some(&**ty) } else { None },
413 /// Prints the docs from a given attribute list unless its tagged no export
414 pub fn writeln_docs<W: std::io::Write>(w: &mut W, attrs: &[syn::Attribute], prefix: &str) {
415 writeln_docs_impl(w, attrs, prefix, None::<(_, _, std::vec::Drain<'_, (String, &syn::Type)>, _, _)>);
418 pub fn writeln_arg_docs<'a, W: std::io::Write, I>(w: &mut W, attrs: &[syn::Attribute], prefix: &str, types: &mut TypeResolver, generics: Option<&GenericTypes>, args: I, ret: Option<&syn::Type>) where I: Iterator<Item = (String, &'a syn::Type)> {
419 writeln_docs_impl(w, attrs, prefix, Some((types, generics, args, ret, None)))
422 pub fn writeln_field_docs<W: std::io::Write>(w: &mut W, attrs: &[syn::Attribute], prefix: &str, types: &mut TypeResolver, generics: Option<&GenericTypes>, field: &syn::Type) {
423 writeln_docs_impl(w, attrs, prefix, Some((types, generics, vec![].drain(..), None, Some(field))))
426 /// Prints the docs from a given attribute list unless its tagged no export
427 fn writeln_docs_impl<'a, W: std::io::Write, I>(w: &mut W, attrs: &[syn::Attribute], prefix: &str, method_args_ret: Option<(&mut TypeResolver, Option<&GenericTypes>, I, Option<&syn::Type>, Option<&syn::Type>)>) where I: Iterator<Item = (String, &'a syn::Type)> {
428 for attr in attrs.iter() {
429 let tokens_clone = attr.tokens.clone();
430 let mut token_iter = tokens_clone.into_iter();
431 if let Some(token) = token_iter.next() {
433 TokenTree::Punct(c) if c.as_char() == '=' => {
434 // syn gets '=' from '///' or '//!' as it is syntax for #[doc = ""]
436 TokenTree::Group(_) => continue, // eg #[derive()]
437 _ => unimplemented!(),
441 syn::AttrStyle::Inner(_) => {
442 match token_iter.next().unwrap() {
443 TokenTree::Literal(lit) => {
444 // Drop the first and last chars from lit as they are always "
445 let doc = format!("{}", lit).trim().replace("\n", &format!("\n{}//!", prefix));
446 writeln!(w, "{}//!{}", prefix, &doc[1..doc.len() - 1]).unwrap();
448 _ => unimplemented!(),
451 syn::AttrStyle::Outer => {
452 match token_iter.next().unwrap() {
453 TokenTree::Literal(lit) => {
454 // Drop the first and last chars from lit as they are always "
455 let doc = format!("{}", lit).trim().replace("\n", &format!("\n{}///", prefix));
456 writeln!(w, "{}///{}", prefix, &doc[1..doc.len() - 1]).unwrap();
458 _ => unimplemented!(),
463 if let Some((types, generics, inp, outp, field_ty)) = method_args_ret {
464 let mut nullable_found = false;
465 for (name, inp) in inp {
466 if types.skip_arg(inp, generics) { continue; }
467 if if let syn::Type::Reference(syn::TypeReference { elem, .. }) = inp {
468 if let syn::Type::Path(syn::TypePath { ref path, .. }) = &**elem {
469 types.is_path_transparent_container(path, generics, true)
471 } else if let syn::Type::Path(syn::TypePath { ref path, .. }) = inp {
472 types.is_path_transparent_container(path, generics, true)
474 // Note downstream clients match this text exactly so any changes may require
475 // changes in the Java and Swift bindings, at least.
476 if !nullable_found { writeln!(w, "{}///", prefix).unwrap(); }
477 nullable_found = true;
478 writeln!(w, "{}/// Note that {} (or a relevant inner pointer) may be NULL or all-0s to represent None", prefix, name).unwrap();
481 if if let Some(syn::Type::Reference(syn::TypeReference { elem, .. })) = outp {
482 if let syn::Type::Path(syn::TypePath { ref path, .. }) = &**elem {
483 types.is_path_transparent_container(path, generics, true)
485 } else if let Some(syn::Type::Path(syn::TypePath { ref path, .. })) = outp {
486 types.is_path_transparent_container(path, generics, true)
488 // Note downstream clients match this text exactly so any changes may require
489 // changes in the Java and Swift bindings, at least.
490 if !nullable_found { writeln!(w, "{}///", prefix).unwrap(); }
491 nullable_found = true;
492 writeln!(w, "{}/// Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None", prefix).unwrap();
494 let field = field_ty.map(|ty| generics.resolve_type(ty));
495 if if let Some(syn::Type::Reference(syn::TypeReference { elem, .. })) = field {
496 if let syn::Type::Path(syn::TypePath { ref path, .. }) = &**elem {
497 let resolved_path = types.resolve_path(path, generics);
498 if types.crate_types.opaques.get(&resolved_path).is_some() {
499 writeln!(w, "{}/// Note that this field is expected to be a reference.", prefix).unwrap();
501 types.is_path_transparent_container(path, generics, true)
503 } else if let Some(syn::Type::Path(syn::TypePath { ref path, .. })) = field {
504 types.is_path_transparent_container(path, generics, true)
506 // Note downstream clients match this text exactly so any changes may require
507 // changes in the Java and Swift bindings, at least.
508 if !nullable_found { writeln!(w, "{}///", prefix).unwrap(); }
509 writeln!(w, "{}/// Note that this (or a relevant inner pointer) may be NULL or all-0s to represent None", prefix).unwrap();
515 /// Print the parameters in a method declaration, starting after the open parenthesis, through and
516 /// including the closing parenthesis and return value, but not including the open bracket or any
517 /// trailing semicolons.
519 /// Usable both for a function definition and declaration.
521 /// this_param is used when returning Self or accepting a self parameter, and should be the
522 /// concrete, mapped type.
523 pub fn write_method_params<W: std::io::Write>(w: &mut W, sig: &syn::Signature, this_param: &str, types: &mut TypeResolver, generics: Option<&GenericTypes>, self_ptr: bool, fn_decl: bool) {
524 if sig.constness.is_some() || sig.asyncness.is_some() || sig.unsafety.is_some() ||
525 sig.abi.is_some() || sig.variadic.is_some() {
528 if sig.generics.lt_token.is_some() {
529 for generic in sig.generics.params.iter() {
531 syn::GenericParam::Type(_)|syn::GenericParam::Lifetime(_) => {
532 // We ignore these, if they're not on skipped args, we'll blow up
533 // later, and lifetimes we just hope the C client enforces.
535 _ => unimplemented!(),
540 let mut first_arg = true;
541 let mut num_unused = 0;
542 for inp in sig.inputs.iter() {
544 syn::FnArg::Receiver(recv) => {
545 if !recv.attrs.is_empty() { unimplemented!(); }
546 write!(w, "{}this_arg: {}{}", if recv.reference.is_none() { "mut " } else { "" },
547 if recv.reference.is_some() {
548 match (self_ptr, recv.mutability.is_some()) {
549 (true, true) => "*mut ",
550 (true, false) => "*const ",
551 (false, true) => "&mut ",
552 (false, false) => "&",
554 } else { "" }, this_param).unwrap();
558 syn::FnArg::Typed(arg) => {
559 if types.skip_arg(&*arg.ty, generics) { continue; }
560 if !arg.attrs.is_empty() { unimplemented!(); }
561 // First get the c type so that we can check if it ends up being a reference:
562 let mut c_type = Vec::new();
563 types.write_c_type(&mut c_type, &*arg.ty, generics, false);
565 syn::Pat::Ident(ident) => {
566 if !ident.attrs.is_empty() || ident.subpat.is_some() {
569 write!(w, "{}{}{}: ", if first_arg { "" } else { ", " }, if !fn_decl || c_type[0] == '&' as u8 || c_type[0] == '*' as u8 { "" } else { "mut " }, ident.ident).unwrap();
572 syn::Pat::Wild(wild) => {
573 if !wild.attrs.is_empty() { unimplemented!(); }
574 write!(w, "{}unused_{}: ", if first_arg { "" } else { ", " }, num_unused).unwrap();
577 _ => unimplemented!(),
579 w.write_all(&c_type).unwrap();
583 write!(w, ")").unwrap();
585 syn::ReturnType::Type(_, rtype) => {
586 write!(w, " -> ").unwrap();
587 if let Some(mut remaining_path) = first_seg_self(&*rtype) {
588 if remaining_path.next().is_none() {
589 write!(w, "{}", this_param).unwrap();
593 types.write_c_type(w, &*rtype, generics, true);
599 /// Print the main part of a method declaration body, starting with a newline after the function
600 /// open bracket and converting each function parameter to or from C-mapped types. Ends with "let
601 /// mut ret = " assuming the next print will be the unmapped Rust function to call followed by the
602 /// parameters we mapped to/from C here.
603 pub fn write_method_var_decl_body<W: std::io::Write>(w: &mut W, sig: &syn::Signature, extra_indent: &str, types: &TypeResolver, generics: Option<&GenericTypes>, to_c: bool) {
604 let mut num_unused = 0u32;
605 for inp in sig.inputs.iter() {
607 syn::FnArg::Receiver(_) => {},
608 syn::FnArg::Typed(arg) => {
609 if types.skip_arg(&*arg.ty, generics) { continue; }
610 if !arg.attrs.is_empty() { unimplemented!(); }
611 macro_rules! write_new_var {
612 ($ident: expr, $ty: expr) => {
614 if types.write_to_c_conversion_new_var(w, &$ident, &$ty, generics, false) {
615 write!(w, "\n\t{}", extra_indent).unwrap();
618 if types.write_from_c_conversion_new_var(w, &$ident, &$ty, generics) {
619 write!(w, "\n\t{}", extra_indent).unwrap();
625 syn::Pat::Ident(ident) => {
626 if !ident.attrs.is_empty() || ident.subpat.is_some() {
629 write_new_var!(ident.ident, *arg.ty);
631 syn::Pat::Wild(w) => {
632 if !w.attrs.is_empty() { unimplemented!(); }
633 write_new_var!(format_ident!("unused_{}", num_unused), *arg.ty);
636 _ => unimplemented!(),
642 syn::ReturnType::Type(_, _) => {
643 write!(w, "let mut ret = ").unwrap();
649 /// Prints the parameters in a method call, starting after the open parenthesis and ending with a
650 /// final return statement returning the method's result. Should be followed by a single closing
653 /// The return value is expected to be bound to a variable named `ret` which is available after a
654 /// method-call-ending semicolon.
655 pub fn write_method_call_params<W: std::io::Write>(w: &mut W, sig: &syn::Signature, extra_indent: &str, types: &TypeResolver, generics: Option<&GenericTypes>, this_type: &str, to_c: bool) {
656 let mut first_arg = true;
657 let mut num_unused = 0;
658 for inp in sig.inputs.iter() {
660 syn::FnArg::Receiver(recv) => {
661 if !recv.attrs.is_empty() { unimplemented!(); }
663 if recv.reference.is_none() { unimplemented!(); }
664 write!(w, "self.this_arg").unwrap();
668 syn::FnArg::Typed(arg) => {
669 if types.skip_arg(&*arg.ty, generics) {
672 write!(w, ", ").unwrap();
675 types.no_arg_to_rust(w, &*arg.ty, generics);
679 if !arg.attrs.is_empty() { unimplemented!(); }
680 macro_rules! write_ident {
683 write!(w, ", ").unwrap();
687 types.write_to_c_conversion_inline_prefix(w, &*arg.ty, generics, false);
688 write!(w, "{}", $ident).unwrap();
689 types.write_to_c_conversion_inline_suffix(w, &*arg.ty, generics, false);
691 types.write_from_c_conversion_prefix(w, &*arg.ty, generics);
692 write!(w, "{}", $ident).unwrap();
693 types.write_from_c_conversion_suffix(w, &*arg.ty, generics);
698 syn::Pat::Ident(ident) => {
699 if !ident.attrs.is_empty() || ident.subpat.is_some() {
702 write_ident!(ident.ident);
704 syn::Pat::Wild(w) => {
705 if !w.attrs.is_empty() { unimplemented!(); }
706 write_ident!(format!("unused_{}", num_unused));
709 _ => unimplemented!(),
714 write!(w, ")").unwrap();
716 syn::ReturnType::Type(_, rtype) => {
717 write!(w, ";\n\t{}", extra_indent).unwrap();
719 let self_segs_iter = first_seg_self(&*rtype);
720 if to_c && first_seg_self(&*rtype).is_some() {
721 // Assume rather blindly that we're returning an associated trait from a C fn call to a Rust trait object.
722 write!(w, "ret").unwrap();
723 } else if !to_c && self_segs_iter.is_some() && self_segs_iter.unwrap().next().is_none() {
724 // If we're returning "Self" (and not "Self::X"), just do it manually
725 write!(w, "{} {{ inner: ObjOps::heap_alloc(ret), is_owned: true }}", this_type).unwrap();
727 let new_var = types.write_from_c_conversion_new_var(w, &format_ident!("ret"), rtype, generics);
729 write!(w, "\n\t{}", extra_indent).unwrap();
731 types.write_from_c_conversion_prefix(w, &*rtype, generics);
732 write!(w, "ret").unwrap();
733 types.write_from_c_conversion_suffix(w, &*rtype, generics);
735 let new_var = types.write_to_c_conversion_new_var(w, &format_ident!("ret"), &rtype, generics, true);
737 write!(w, "\n\t{}", extra_indent).unwrap();
739 types.write_to_c_conversion_inline_prefix(w, &rtype, generics, true);
740 write!(w, "ret").unwrap();
741 types.write_to_c_conversion_inline_suffix(w, &rtype, generics, true);
748 /// Prints concrete generic parameters for a struct/trait/function, including the less-than and
749 /// greater-than symbols, if any generic parameters are defined.
750 pub fn maybe_write_generics<W: std::io::Write>(w: &mut W, generics: &syn::Generics, generics_impld: &syn::PathArguments, types: &TypeResolver, concrete_lifetimes: bool) {
751 maybe_write_generics_intern(w, generics, generics_impld, types, concrete_lifetimes, false);
754 pub fn maybe_write_non_lifetime_generics<W: std::io::Write>(w: &mut W, generics: &syn::Generics, generics_impld: &syn::PathArguments, types: &TypeResolver) {
755 maybe_write_generics_intern(w, generics, generics_impld, types, false, true);
758 fn maybe_write_generics_intern<W: std::io::Write>(w: &mut W, generics: &syn::Generics, generics_impld: &syn::PathArguments, types: &TypeResolver, concrete_lifetimes: bool, dummy_lifetimes: bool) {
759 let mut gen_types = GenericTypes::new(None);
760 assert!(gen_types.learn_generics(generics, types));
761 if generics.params.is_empty() { return; }
762 for generic in generics.params.iter() {
764 syn::GenericParam::Type(type_param) => {
765 for bound in type_param.bounds.iter() {
767 syn::TypeParamBound::Trait(t) => {
768 if let Some(trait_bound) = types.maybe_resolve_path(&t.path, None) {
769 if types.skip_path(&trait_bound) {
770 // Just hope rust deduces generic params if some bounds are skipable.
783 write!(w, "<").unwrap();
784 for (idx, generic) in generics.params.iter().enumerate() {
786 syn::GenericParam::Type(type_param) => {
787 write!(w, "{}", if idx != 0 { ", " } else { "" }).unwrap();
788 let type_ident = &type_param.ident;
789 if types.understood_c_type(&syn::parse_quote!(#type_ident), Some(&gen_types)) {
790 types.write_c_type_in_generic_param(w, &syn::parse_quote!(#type_ident), Some(&gen_types), false);
792 if let syn::PathArguments::AngleBracketed(args) = generics_impld {
793 if let syn::GenericArgument::Type(ty) = &args.args[idx] {
794 types.write_c_type_in_generic_param(w, &ty, Some(&gen_types), false);
799 syn::GenericParam::Lifetime(lt) => {
801 write!(w, "'_").unwrap();
802 } else if concrete_lifetimes {
803 write!(w, "'static").unwrap();
805 write!(w, "{}'{}", if idx != 0 { ", " } else { "" }, lt.lifetime.ident).unwrap();
808 _ => unimplemented!(),
811 write!(w, ">").unwrap();
814 pub fn maybe_write_lifetime_generics<W: std::io::Write>(w: &mut W, generics: &syn::Generics, types: &TypeResolver) {
815 let mut gen_types = GenericTypes::new(None);
816 assert!(gen_types.learn_generics(generics, types));
817 if generics.params.iter().any(|param| if let syn::GenericParam::Lifetime(_) = param { true } else { false }) {
818 write!(w, "<").unwrap();
819 for (idx, generic) in generics.params.iter().enumerate() {
821 syn::GenericParam::Type(_) => {},
822 syn::GenericParam::Lifetime(lt) => {
823 write!(w, "{}'{}", if idx != 0 { ", " } else { "" }, lt.lifetime.ident).unwrap();
825 _ => unimplemented!(),
828 write!(w, ">").unwrap();