### Example calling a_crate::a_func in examples/ex.rs Source: https://docs.rs/proctitle/latest/scrape-examples-help.html Shows an example file that calls the public function from the library crate, which will be scraped and included in the documentation for that function. ```rust // examples/ex.rs fn main() { a_crate::a_func(); } ``` -------------------------------- ### Example usage in examples/hello.rs Source: https://docs.rs/proctitle/latest/proctitle/fn.set_title.html?search=std%3A%3Avec Shows a loop that repeatedly sets the process title to a formatted string with an incrementing counter, then sleeps for 500 milliseconds. The example is from the repository's `examples/hello.rs` file. ```rust fn main() { let mut i = 0; loop { proctitle::set_title(format!("Hello, world, {}", i)); i += 1; std::thread::sleep(std::time::Duration::from_millis(500)); } } ``` -------------------------------- ### Example public function in src/lib.rs Source: https://docs.rs/proctitle/latest/scrape-examples-help.html Shows a simple public function in a library's source code that can be documented and scraped for examples. ```rust // src/lib.rs pub fn a_func() {} ``` -------------------------------- ### Command to enable scraping examples with cargo doc Source: https://docs.rs/proctitle/latest/scrape-examples-help.html Command to run cargo doc with unstable options to enable Rustdoc's example scraping feature. ```bash cargo doc -Zunstable-options -Zrustdoc-scrape-examples ``` -------------------------------- ### proctitle lib.rs: platform-specific set_title implementations Source: https://docs.rs/proctitle/latest/src/proctitle/lib.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Complete lib.rs for the proctitle crate. It defines a platform-specific `imp` module with `set_title` for BSD (using `setproctitle`), Linux (using `libc::prctl` with `PR_SET_NAME`), Windows (using `SetConsoleTitleW` and a named event handle), and a no-op fallback for other targets. Includes tests for Linux, Windows, and a generic callable test. ```rust 1#![cfg_attr(feature = "nightly", feature(external_doc))] 2#![cfg_attr(feature = "nightly", doc(include = "../README.md"))] 3 4#[cfg(any( 5 target_os = "freebsd", 6 target_os = "dragonfly", 7 target_os = "netbsd", 8 target_os = "openbsd", 9 target_os = "bitrig", 10))] 11mod imp { 12 use std::ffi::CString; 13 use std::ffi::OsStr; 14 use std::os::unix::ffi::OsStrExt; 15 16 /// Set a process title, or some approximation of it, if possible. 17 pub fn set_title>(title: T) { 18 if let Ok(title) = CString::new(title.as_ref().to_owned().as_bytes()) { 19 unsafe { 20 setproctitle(b"-%s\0".as_ptr(), title.as_ptr()); 21 } 22 } 23 } 24 25 #[link(name = "c")] 26 extern "C" { 27 fn setproctitle(fmt: *const u8, ...); 28 } 29} 30 31#[cfg(target_os = "linux")] 32mod imp { 33 use libc; 34 use std::ffi::CString; 35 use std::ffi::OsStr; 36 use std::os::unix::ffi::OsStrExt; 37 38 /// Set a process title, or some approximation of it, if possible. 39 pub fn set_title>(title: T) { 40 if let Ok(title) = CString::new(title.as_ref().to_owned().as_bytes()) { 41 unsafe { libc::prctl(libc::PR_SET_NAME, title.as_ptr(), 0, 0, 0) }; 42 } 43 } 44 45 #[test] 46 fn set_title_sets_name() { 47 use libc; 48 set_title("abcdefghijklmnopqrstu"); 49 50 let mut buf = [0u8; 16]; 51 unsafe { libc::prctl(libc::PR_GET_NAME, buf.as_mut_ptr(), 0, 0, 0) }; 52 assert_eq!(&buf, b"abcdefghijklmno\0"); 53 } 54} 55 56#[cfg(target_os = "windows")] 57mod imp { 58 use std::ffi::OsStr; 59 use std::os::windows::ffi::OsStrExt; 60 use std::sync::Mutex; 61 62 use lazy_static::lazy_static; 63 use winapi::um::handleapi::CloseHandle; 64 use winapi::um::synchapi::CreateEventW; 65 use winapi::um::wincon::SetConsoleTitleW; 66 use winapi::um::winnt::HANDLE; 67 68 struct NamedHandle(HANDLE); 69 unsafe impl Send for NamedHandle {} 70 71 impl From> for NamedHandle { 72 fn from(t: Vec) -> Self { 73 assert!(t.ends_with(&[0])); 74 75 Self(unsafe { CreateEventW(std::ptr::null_mut(), 1, 0, t.as_ptr()) }) 76 } 77 } 78 79 impl Drop for NamedHandle { 80 fn drop(&mut self) { 81 if !self.0.is_null() { 82 unsafe { CloseHandle(self.0) }; 83 } 84 } 85 } 86 87 lazy_static! { 88 static ref EVENT_HANDLE: Mutex> = Mutex::new(None); 89 } 90 91 /// Set a process title, or some approximation of it, if possible. 92 pub fn set_title>(title: T) { 93 // Windows doesn't appear to have a userspace mechanism to name the current 94 // process. 95 // 96 // Try to set a console title, and in case we're not attached to one, 97 // follow PostgreSQL's lead and create a named event handle that can be 98 // found in Process Explorer, Process Hacker, etc. 99 let mut t: Vec = title.as_ref().encode_wide().take(1024).collect(); 100 t.push(0); 101 102 unsafe { SetConsoleTitleW(t.as_ptr()) }; 103 104 EVENT_HANDLE 105 .lock() 106 .expect("event handle lock") 107 .replace(NamedHandle::from(t)); 108 } 109 110 #[test] 111 fn set_title_sets_console_title_and_makes_a_handle() { 112 let title = "Pinkle, squirmy, blib, blab, blob"; 113 set_title(title); 114 115 let mut t: Vec = std::ffi::OsString::from(title).encode_wide().collect(); 116 t.push(0); 117 let mut buf = vec![0; t.len()]; 118 let len = 119 unsafe { winapi::um::wincon::GetConsoleTitleW(buf.as_mut_ptr(), buf.len() as u32) }; 120 121 assert_eq!(len, title.len() as u32, "length mismatch"); 122 assert_eq!(buf, t, "buffer mismatch"); 123 assert!( 124 EVENT_HANDLE.lock().unwrap().is_some(), 125 "event handle missing" 126 ); 127 } 128} 129 130#[cfg(not(any( 131 target_os = "freebsd", 132 target_os = "dragonfly", 133 target_os = "netbsd", 134 target_os = "openbsd", 135 target_os = "bitrig", 136 target_os = "linux", 137 target_os = "windows" 138)))] 139mod imp { 140 use std::ffi::OsStr; 141 142 /// Set a process title, or some approximation of it, if possible. 143 pub fn set_title>(_title: T) {} 144} 145 146pub use self::imp::*; 147 148// This races against the SetConsoleTitle() tests on Windows 149#[cfg(not(windows))] 150#[test] 151fn set_title_is_at_least_callable() { 152 set_title("What was it like being a hamster?"); 153 set_title(String::from("It was better than being a chicken.")); 154 set_title(std::ffi::OsString::from( 155 "Have you seen the size of an egg?", 156 )); 157} ``` -------------------------------- ### BSD-like systems: set_title using setproctitle Source: https://docs.rs/proctitle/latest/src/proctitle/lib.rs.html Implementation for FreeBSD, DragonFly, NetBSD, OpenBSD, and Bitrig. It converts the title to a CString and calls the C `setproctitle` function with a format string `-%s`. The function is unsafe and requires the `libc` link. ```rust #![cfg_attr(feature = "nightly", feature(external_doc))] #![cfg_attr(feature = "nightly", doc(include = "../README.md"))] #[cfg(any( target_os = "freebsd", target_os = "dragonfly", target_os = "netbsd", target_os = "openbsd", target_os = "bitrig", ))] mod imp { use std::ffi::CString; use std::ffi::OsStr; use std::os::unix::ffi::OsStrExt; /// Set a process title, or some approximation of it, if possible. pub fn set_title>(title: T) { if let Ok(title) = CString::new(title.as_ref().to_owned().as_bytes()) { unsafe { setproctitle(b"-%s\0".as_ptr(), title.as_ptr()); } } } #[link(name = "c")] extern "C" { fn setproctitle(fmt: *const u8, ...); } } ``` -------------------------------- ### set_title Source: https://docs.rs/proctitle/latest/proctitle/fn.set_title.html?search=std%3A%3Avec Documentation for the set_title function in the proctitle crate. ```APIDOC ## set_title ### Description Sets a process title, or some approximation of it, if possible. ### Function Signature ```rust pub fn set_title>(title: T) ``` ### Parameters - **title** (`T` where `T: AsRef`) - Required - The new process title to set. ### Example ```rust proctitle::set_title(format!("Hello, world, {}", i)); ``` ``` -------------------------------- ### set_title Source: https://docs.rs/proctitle/latest/proctitle/fn.set_title.html Sets the process title to the given string, or an approximation if the platform does not support exact titles. ```APIDOC ## set_title ### Description Sets the process title to the given string, or an approximation if the platform does not support exact titles. ### Function Signature ```rust pub fn set_title>(title: T) ``` ### Parameters - `title` (T) - Required - The new process title. Accepts any type that implements `AsRef`. ### Example ```rust proctitle::set_title(format!("Hello, world, {}", i)); ``` ``` -------------------------------- ### Windows: set_title using console title and named event handle Source: https://docs.rs/proctitle/latest/src/proctitle/lib.rs.html Implementation for Windows. It sets the console title via `SetConsoleTitleW` and creates a named event handle (using `CreateEventW`) that can be found in tools like Process Explorer. Includes a test verifying the console title and handle creation. ```rust #[cfg(target_os = "windows")] mod imp { use std::ffi::OsStr; use std::os::windows::ffi::OsStrExt; use std::sync::Mutex; use lazy_static::lazy_static; use winapi::um::handleapi::CloseHandle; use winapi::um::synchapi::CreateEventW; use winapi::um::wincon::SetConsoleTitleW; use winapi::um::winnt::HANDLE; struct NamedHandle(HANDLE); unsafe impl Send for NamedHandle {} impl From> for NamedHandle { fn from(t: Vec) -> Self { assert!(t.ends_with(&[0])); Self(unsafe { CreateEventW(std::ptr::null_mut(), 1, 0, t.as_ptr()) }) } } impl Drop for NamedHandle { fn drop(&mut self) { if !self.0.is_null() { unsafe { CloseHandle(self.0) }; } } } lazy_static! { static ref EVENT_HANDLE: Mutex> = Mutex::new(None); } /// Set a process title, or some approximation of it, if possible. pub fn set_title>(title: T) { // Windows doesn't appear to have a userspace mechanism to name the current // process. // // Try to set a console title, and in case we're not attached to one, // follow PostgreSQL's lead and create a named event handle that can be // found in Process Explorer, Process Hacker, etc. let mut t: Vec = title.as_ref().encode_wide().take(1024).collect(); t.push(0); unsafe { SetConsoleTitleW(t.as_ptr()) }; EVENT_HANDLE .lock() .expect("event handle lock") .replace(NamedHandle::from(t)); } #[test] fn set_title_sets_console_title_and_makes_a_handle() { let title = "Pinkle, squirmy, blib, blab, blob"; set_title(title); let mut t: Vec = std::ffi::OsString::from(title).encode_wide().collect(); t.push(0); let mut buf = vec![0; t.len()]; let len = unsafe { winapi::um::wincon::GetConsoleTitleW(buf.as_mut_ptr(), buf.len() as u32) }; assert_eq!(len, title.len() as u32, "length mismatch"); assert_eq!(buf, t, "buffer mismatch"); assert!( EVENT_HANDLE.lock().unwrap().is_some(), "event handle missing" ); } } ``` -------------------------------- ### Fallback: no-op set_title for unsupported platforms Source: https://docs.rs/proctitle/latest/src/proctitle/lib.rs.html Implementation for platforms not covered by the specific OS modules. The `set_title` function does nothing. ```rust #[cfg(not(any( target_os = "freebsd", target_os = "dragonfly", target_os = "netbsd", target_os = "openbsd", target_os = "bitrig", target_os = "linux", target_os = "windows" )))] mod imp { use std::ffi::OsStr; /// Set a process title, or some approximation of it, if possible. pub fn set_title>(_title: T) {} } ``` -------------------------------- ### Set process title in a loop with proctitle::set_title Source: https://docs.rs/proctitle/latest/src/hello/hello.rs.html?search=u32+-%3E+bool Continuously updates the process title with an incrementing counter every 500 milliseconds. Requires the proctitle crate and is intended for testing or demonstrating the set_title function. ```rust use proctitle; fn main() { let mut i = 0; loop { proctitle::set_title(format!("Hello, world, {}", i)); i += 1; std::thread::sleep(std::time::Duration::from_millis(500)); } } ``` -------------------------------- ### Linux: set_title using prctl and test Source: https://docs.rs/proctitle/latest/src/proctitle/lib.rs.html Implementation for Linux using `libc::prctl` with `PR_SET_NAME`. Includes a test that sets a long title and verifies it is truncated to 15 characters plus null terminator. ```rust #[cfg(target_os = "linux")] mod imp { use libc; use std::ffi::CString; use std::ffi::OsStr; use std::os::unix::ffi::OsStrExt; /// Set a process title, or some approximation of it, if possible. pub fn set_title>(title: T) { if let Ok(title) = CString::new(title.as_ref().to_owned().as_bytes()) { unsafe { libc::prctl(libc::PR_SET_NAME, title.as_ptr(), 0, 0, 0) }; } } #[test] fn set_title_sets_name() { use libc; set_title("abcdefghijklmnopqrstu"); let mut buf = [0u8; 16]; unsafe { libc::prctl(libc::PR_GET_NAME, buf.as_mut_ptr(), 0, 0, 0) }; assert_eq!(&buf, b"abcdefghijklmno\0"); } } ``` -------------------------------- ### Function signature: proctitle::set_title Source: https://docs.rs/proctitle/latest/proctitle/fn.set_title.html?search=std%3A%3Avec Declares the public function `set_title` that accepts any type implementing `AsRef` and returns `()`. Use it to set the process title to an approximation if possible. ```rust pub fn set_title>(title: T) ``` -------------------------------- ### Re-export and generic test for set_title Source: https://docs.rs/proctitle/latest/src/proctitle/lib.rs.html Re-exports the platform-specific `imp` module and includes a test that verifies `set_title` is callable with various string types on non-Windows platforms. ```rust pub use self::imp::*; // This races against the SetConsoleTitle() tests on Windows #[cfg(not(windows))] #[test] fn set_title_is_at_least_callable() { set_title("What was it like being a hamster?"); set_title(String::from("It was better than being a chicken.")); set_title(std::ffi::OsString::from( "Have you seen the size of an egg?", )); } ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.