Struct videocore_gencmd::global::GlobalInstance

pub struct GlobalInstance { /* fields omitted */ }

Implementations

impl GlobalInstance

pub fn instance<const SPIN_RETRY_LIMIT: usize>(
) -> Result<Arc<Mutex<Self>>, GencmdInitError>

Returns a singleton instance.

If the instance already exists, the same instance is returned.

Otherwise a new instance is created using Self::new.

Memory race

There is a race between the last strong reference being decremented and dropped and the GlobalInstance inside of it being deinitialized. This means that for a little while this function may return GencmdInitError::AlreadyInitialized even when the global singleton is no longer being held.

                           GlobalInstnace Drop starts
                           |    Error here as an instance still exists
                           |    |    GlobalInstnace Drop ends
                           v    v    v
ONE_INSTANCE: |------------|_________|
Weak Arc    : |-------|_________|....
Strong Arc  : |-------|         |....
                      ^         ^
                      |         Attempt to create new singleton instance
                      Drop Arc here, weak becomes non-upgradable

To alleviate this, this function may spin around that error until the GlobalInstnace::drop finishes. However, if the second instance is being held by an external actor and not through the global singleton functionality, then the spin will never finish unless it is limited. For that purpose, this function takes the SPIN_RETRY_LIMIT generic argument which can be used to limit the maximum number of retry spins before an error is returned (that is, new will be attempted SPIN_RETRY_LIMIT + 1 times).

impl GlobalInstance

pub fn new() -> Result<Self, GencmdInitError>

Initializes a new instance of videocore connection.

Returns an error if another connection already exists.

It is up to the caller to share that one connection to all places where they might need it. However, if “global_singleton” feature is enabled, a global, lazy singleton implementation is provided in singleton module.

pub unsafe fn send_command(
    &mut self,
    command: &CStr
) -> Result<(), GencmdCmdError>

Sends a command to the instance.

Panic

Will panic if this instance has been deinitialized.

Safety

Looks like the response must be picked up before another thread issues a send, otherwise the entire system gets broken and all communication with vc gencmd starts going haywire.

pub fn retrieve_response(
    &mut self,
    buffer: &mut [u8]
) -> Result<usize, GencmdCmdError>

Retrieves the response from the instance.

Returns number of bytes read into buffer (excluding the null terminator).

Panic

Will panic if this instance has been deinitialized.

pub fn is_deinitialized(&self) -> bool

Returns true if self.deinit has been called at least once on this instance.

pub fn deinit(self) -> Result<(), GencmdDeinitError>

Deinitializes self, returning a potential error.

If deinit is not called,deinit_ref_mut will be called in drop and will panic on error.

pub fn deinit_ref_mut(&mut self) -> Result<(), GencmdDeinitError>

Deinitializes self, returning a potential error.

It’s okay to call this multiple times, but after a deinitialization other methods that work with this instance will panic.

If deinit_ref_mut is not called it will be called in drop and will panic on error.

Trait Implementations

impl Drop for GlobalInstance

fn drop(&mut self)

Executes the destructor for this type.

impl Send for GlobalInstance