pub struct TracepointState { /* private fields */ }Expand description
Low-level API: Represents a tracepoint registration.
Implementations§
Source§impl TracepointState
impl TracepointState
Sourcepub const fn new(initial_enable_status: u32) -> Self
pub const fn new(initial_enable_status: u32) -> Self
Creates a new unregistered tracepoint.
initial_enable_status is normally 0, since an unregistered tracepoint will normally be considered disabled.
Sourcepub fn enabled(&self) -> bool
pub fn enabled(&self) -> bool
Returns true if this tracepoint is enabled, i.e. enable_status != 0.
Sourcepub fn unregister(&self) -> i32
pub fn unregister(&self) -> i32
Unregisters this tracepoint.
Returns 0 for success, error code (e.g. EBUSY, EALREADY) for error. Error code is usually ignored in retail code, but may be helpful during development to understand behavior or track down issues.
Sourcepub unsafe fn register(self: Pin<&Self>, _name_args: &CStr) -> i32
pub unsafe fn register(self: Pin<&Self>, _name_args: &CStr) -> i32
Registers this tracepoint.
Requires: this TracepointState is not currently registered.
Returns 0 for success, error code (e.g. EACCES, ENOENT) for error. The error code is usually ignored in retail scenarios but may be helpful during development to understand behavior or track down issues.
_name_args is the tracepoint definition in the format
Name[ FieldDef1[; FieldDef2...]]. For example:
MyTracepoint1MyTracepoint2 u32 Field1MyTracepoint3 u32 Field1; char Field2[20]
§Safety
The tracepoint must be unregistered before it is deallocated. TracepointState
will unregister itself when dropped, so this is only an issue if the tracepoint
is not dropped before it is deallocated. This might happen for a static variable
in a shared library that gets unloaded.
Sourcepub unsafe fn register_with_flags(
self: Pin<&Self>,
_name_args: &CStr,
_flags: u16,
) -> i32
pub unsafe fn register_with_flags( self: Pin<&Self>, _name_args: &CStr, _flags: u16, ) -> i32
Advanced: Registers this tracepoint using the specified user_reg flags.
Requires: this TracepointState is not currently registered.
Returns 0 for success, error code (e.g. EACCES, ENOENT) for error. The error code is usually ignored in retail scenarios but may be helpful during development to understand behavior or track down issues.
_name_args is the tracepoint definition in the format
Name[ FieldDef1[; FieldDef2...]]. For example:
MyTracepoint1MyTracepoint2 u32 Field1MyTracepoint3 u32 Field1; char Field2[20]
_flags is normally 0, but may also be set to a user_reg flag such as
USER_EVENT_REG_PERSIST.
§Safety
The tracepoint must be unregistered before it is deallocated. TracepointState
will unregister itself when dropped, so this is only an issue if the tracepoint
is not dropped before it is deallocated. This might happen for a static variable
in a shared library that gets unloaded.
Sourcepub fn write(&self, data: &mut [EventDataDescriptor<'_>]) -> i32
pub fn write(&self, data: &mut [EventDataDescriptor<'_>]) -> i32
Generates an event.
Requires: data[0].is_empty() since it will be used for the event headers.
Returns 0 for success, error code (e.g. EBADF) for error. The error code is usually ignored in retail scenarios but may be helpful during development to understand behavior or track down issues.
If disabled or unregistered, this method does nothing and returnes EBADF.
Otherwise, sets data[0] = write_index then sends data[..] to the
user_events_data file handle.
The event’s payload is the concatenation of the remaining data blocks, if any
(i.e. data[1..]).
The payload’s layout should match the args specified in the call to register.
Sourcepub fn write_with_headers(
&self,
data: &mut [EventDataDescriptor<'_>],
headers: &mut [u8],
) -> i32
pub fn write_with_headers( &self, data: &mut [EventDataDescriptor<'_>], headers: &mut [u8], ) -> i32
Generates an event with headers.
Requires: data[0].is_empty() since it will be used for the event headers;
headers.len() >= 4 since it will be used for write_index.
Returns 0 for success, error code (e.g. EBADF) for error. The error code is usually ignored in retail scenarios but may be helpful during development to understand behavior or track down issues.
If disabled or unregistered, this method does nothing and returnes EBADF.
Otherwise, sets data[0] = headers and headers[0..4] = write_index, then sends
data[..] to the user_events_data file.
The event’s payload is the concatenation of the remaining data blocks, if any
(i.e. data[1..]).
The payload’s layout should match the args specified in the call to register.