Struct visa_rs::Instrument
source · [−]pub struct Instrument(_);
Expand description
Session to a specified resource
Implementations
sourceimpl Instrument
impl Instrument
sourcepub fn visa_flush(&self, mode: FlushMode) -> Result<()>
pub fn visa_flush(&self, mode: FlushMode) -> Result<()>
Manually flushes the specified buffers associated with formatted I/O operations and/or serial communication.
sourcepub fn status_desc(&self, error: Error) -> Result<VisaString>
pub fn status_desc(&self, error: Error) -> Result<VisaString>
Returns a user-readable description of the status code passed to the operation.
sourcepub fn lock(
&self,
mode: AccessMode,
timeout: Duration,
key: Option<AccessKey>
) -> Result<Option<AccessKey>>
pub fn lock(
&self,
mode: AccessMode,
timeout: Duration,
key: Option<AccessKey>
) -> Result<Option<AccessKey>>
Establishes an access mode to the specified resources.
This operation is used to obtain a lock on the specified resource. The caller can specify the type of lock requested—exclusive or shared lock—and the length of time the operation will suspend while waiting to acquire the lock before timing out. This operation can also be used for sharing and nesting locks.
The session that gained a shared lock can pass the accessKey to other sessions for the purpose of sharing the lock. The session wanting to join the group of sessions sharing the lock can use the key as an input value to the requestedKey parameter. VISA will add the session to the list of sessions sharing the lock, as long as the requestedKey value matches the accessKey value for the particular resource. The session obtaining a shared lock in this manner will then have the same access privileges as the original session that obtained the lock.
It is also possible to obtain nested locks through this operation. To acquire nested locks, invoke the viLock() operation with the same lock type as the previous invocation of this operation. For each session, viLock() and viUnlock() share a lock count, which is initialized to 0. Each invocation of viLock() for the same session (and for the same lockType) increases the lock count. In the case of a shared lock, it returns with the same accessKey every time. When a session locks the resource a multiple number of times, it is necessary to invoke the viUnlock() operation an equal number of times in order to unlock the resource. That is, the lock count increments for each invocation of viLock(), and decrements for each invocation of viUnlock(). A resource is actually unlocked only when the lock count is 0.
The VISA locking mechanism enforces arbitration of accesses to resources on an individual basis. If a session locks a resource, operations invoked by other sessions to the same resource are serviced or returned with a locking error, depending on the operation and the type of lock used. If a session has an exclusive lock, other sessions cannot modify global attributes or invoke operations, but can still get attributes and set local attributes. If the session has a shared lock, other sessions that have shared locks can also modify global attributes and invoke operations. Regardless of which type of lock a session has, if the session is closed without first being unlocked, VISA automatically performs a viUnlock() on that session.
The locking mechanism works for all processes and resources existing on the same computer. When using remote resources, however, the networking protocol may not provide the ability to pass lock requests to the remote device or resource. In this case, locks will behave as expected from multiple sessions on the same computer, but not necessarily on the remote device. For example, when using the VXI-11 protocol, exclusive lock requests can be sent to a device, but shared locks can only be handled locally.
see also Self::lock_exclusive
, Self::lock_shared
and Self::lock_shared_with_key
pub fn lock_exclusive(&self, timeout: Duration) -> Result<()>
sourcepub fn enable_event(
&self,
event_kind: EventKind,
mechanism: Mechanism
) -> Result<()>
pub fn enable_event(
&self,
event_kind: EventKind,
mechanism: Mechanism
) -> Result<()>
Enables notification of a specified event.
The specified session can be enabled to queue events by specifying VI_QUEUE. Applications can enable the session to invoke a callback function to execute the handler by specifying VI_HNDLR. The applications are required to install at least one handler to be enabled for this mode. Specifying VI_SUSPEND_HNDLR enables the session to receive callbacks, but the invocation of the handler is deferred to a later time. Successive calls to this operation replace the old callback mechanism with the new callback mechanism.
Specifying VI_ALL_ENABLED_EVENTS for the eventType parameter refers to all events which have previously been enabled on this session, making it easier to switch between the two callback mechanisms for multiple events.
NI-VISA does not support enabling both the queue and the handler for the same event type on the same session. If you need to use both mechanisms for the same event type, you should open multiple sessions to the resource.
sourcepub fn disable_event(
&self,
event_kind: EventKind,
mechanism: Mechanism
) -> Result<()>
pub fn disable_event(
&self,
event_kind: EventKind,
mechanism: Mechanism
) -> Result<()>
Disables notification of the specified event type(s) via the specified mechanism(s).
The viDisableEvent() operation disables servicing of an event identified by the eventType parameter for the mechanisms specified in the mechanism parameter. This operation prevents new event occurrences from being added to the queue(s). However, event occurrences already existing in the queue(s) are not flushed. Use viDiscardEvents() if you want to discard events remaining in the queue(s).
Specifying VI_ALL_ENABLED_EVENTS for the eventType parameter allows a session to stop receiving all events. The session can stop receiving queued events by specifying VI_QUEUE. Applications can stop receiving callback events by specifying either VI_HNDLR or VI_SUSPEND_HNDLR. Specifying VI_ALL_MECH disables both the queuing and callback mechanisms.
sourcepub fn discard_events(
&self,
event: EventKind,
mechanism: Mechanism
) -> Result<()>
pub fn discard_events(
&self,
event: EventKind,
mechanism: Mechanism
) -> Result<()>
Discards event occurrences for specified event types and mechanisms in a session.
The viDiscardEvents() operation discards all pending occurrences of the specified event types and mechanisms from the specified session. Specifying VI_ALL_ENABLED_EVENTS for the eventType parameter discards events of every type that is enabled for the given session.
The information about all the event occurrences which have not yet been handled is discarded. This operation is useful to remove event occurrences that an application no longer needs. The discarded event occurrences are not available to a session at a later time.
This operation does not apply to event contexts that have already been delivered to the application.
sourcepub fn wait_on_event(
&self,
event_kind: EventKind,
timeout: Duration
) -> Result<Event>
pub fn wait_on_event(
&self,
event_kind: EventKind,
timeout: Duration
) -> Result<Event>
Waits for an occurrence of the specified event for a given session.
The viWaitOnEvent() operation suspends the execution of a thread of an application and waits for an event of the type specified by inEventType for a time period specified by timeout. You can wait only for events that have been enabled with the viEnableEvent() operation. Refer to individual event descriptions for context definitions. If the specified inEventType is VI_ALL_ENABLED_EVENTS, the operation waits for any event that is enabled for the given session. If the specified timeout value is VI_TMO_INFINITE, the operation is suspended indefinitely. If the specified timeout value is VI_TMO_IMMEDIATE, the operation is not suspended; therefore, this value can be used to dequeue events from an event queue.
When the outContext handle returned from a successful invocation of viWaitOnEvent() is no longer needed, it should be passed to viClose().
If a session’s event queue becomes full and a new event arrives, the new event is discarded. The default event queue size (per session) is 50, which is sufficiently large for most applications. If an application expects more than 50 events to arrive without having been handled, it can modify the value of the attribute VI_ATTR_MAX_QUEUE_LENGTH to the required size.
sourcepub fn install_handler<F: Callback>(
&self,
event_kind: EventKind,
callback: F
) -> Result<Handler<'_, F>>
pub fn install_handler<F: Callback>(
&self,
event_kind: EventKind,
callback: F
) -> Result<Handler<'_, F>>
Installs handlers for event callbacks.
The viInstallHandler() operation allows applications to install handlers on sessions. The handler specified in the handler parameter is installed along with any previously installed handlers for the specified event.
VISA allows applications to install multiple handlers for an eventType on the same session. You can install multiple handlers through multiple invocations of the viInstallHandler() operation, where each invocation adds to the previous list of handlers. If more than one handler is installed for an eventType, each of the handlers is invoked on every occurrence of the specified event(s). VISA specifies that the handlers are invoked in Last In First Out (LIFO) order.
Note: for some reason pass a closure with signature |instr, event|{...}
may get error. Instead, use |instr: & Instrument, event: & Event|{...}
.
sourcepub fn read_stb(&self) -> Result<u16>
pub fn read_stb(&self) -> Result<u16>
Reads a status byte of the service request.
The IEEE 488.2 standard defines several bit assignments in the status byte. For example, if bit 6 of the status is set, the device is requesting service. In addition to setting bit 6 when requesting service, 488.2 devices also use two other bits to specify their status. Bit 4, the Message Available bit (MAV), is set when the device is ready to send previously queried data. Bit 5, the Event Status bit (ESB), is set if one or more of the enabled 488.2 events occurs. These events include power-on, user request, command error, execution error, device dependent error, query error, request control, and operation complete. The device can assert SRQ when ESB or MAV are set, or when a manufacturer-defined condition occurs. Manufacturers of 488.2 devices use the remaining lower-order bits to communicate the reason for the service request or to summarize the device state.
sourceimpl Instrument
impl Instrument
sourcepub unsafe fn visa_read_async(&self, buf: &mut [u8]) -> Result<JobID>
pub unsafe fn visa_read_async(&self, buf: &mut [u8]) -> Result<JobID>
Reads data from device or interface asynchronously.
The viReadAsync() operation asynchronously transfers data. The data read is to be stored in the buffer represented by buf. This operation normally returns before the transfer terminates.
Before calling this operation, you should enable the session for receiving I/O completion events. After the transfer has completed, an I/O completion event is posted.
The operation returns jobId, which you can use with either viTerminate() to abort the operation, or with an I/O completion event to identify which asynchronous read operation completed. VISA will never return VI_NULL for a valid jobID.
If you have enabled VI_EVENT_IO_COMPLETION for queueing (VI_QUEUE), for each successful call to viReadAsync(), you must call viWaitOnEvent() to retrieve the I/O completion event. This is true even if the I/O is done synchronously (that is, if the operation returns VI_SUCCESS_SYNC).
Safety
This function is unsafe because the buf
passed in may be dropped before the transfer terminates
sourcepub unsafe fn visa_write_async(&self, buf: &[u8]) -> Result<JobID>
pub unsafe fn visa_write_async(&self, buf: &[u8]) -> Result<JobID>
The viWriteAsync() operation asynchronously transfers data. The data to be written is in the buffer represented by buf. This operation normally returns before the transfer terminates.
Before calling this operation, you should enable the session for receiving I/O completion events. After the transfer has completed, an I/O completion event is posted.
The operation returns a job identifier that you can use with either viTerminate() to abort the operation or with an I/O completion event to identify which asynchronous write operation completed. VISA will never return VI_NULL for a valid jobId.
If you have enabled VI_EVENT_IO_COMPLETION for queueing (VI_QUEUE), for each successful call to viWriteAsync(), you must call viWaitOnEvent() to retrieve the I/O completion event. This is true even if the I/O is done synchronously (that is, if the operation returns VI_SUCCESS_SYNC).
Safety
This function is unsafe because the buf
passed in may be dropped before the transfer terminates
sourcepub fn terminate(&self, job_id: JobID) -> Result<()>
pub fn terminate(&self, job_id: JobID) -> Result<()>
Requests session to terminate normal execution of an operation.
This operation is used to request a session to terminate normal execution of an operation, as specified by the jobId parameter. The jobId parameter is a unique value generated from each call to an asynchronous operation.
If a user passes VI_NULL as the jobId value to viTerminate(), VISA will abort any calls in the current process executing on the specified vi. Any call that is terminated this way should return VI_ERROR_ABORT. Due to the nature of multi-threaded systems, for example where operations in other threads may complete normally before the operation viTerminate() has any effect, the specified return value is not guaranteed.
sourcepub async fn async_read(&self, buf: &mut [u8]) -> Result<usize>
pub async fn async_read(&self, buf: &mut [u8]) -> Result<usize>
Safe rust wrapper of Self::visa_read_async
Note: for now this function returns a future holding reference of buf
and Self
,
which means it can’t be send to another thread
sourcepub async fn async_write(&self, buf: &[u8]) -> Result<usize>
pub async fn async_write(&self, buf: &[u8]) -> Result<usize>
Safe rust wrapper of Self::visa_write_async
Note: for now this function returns a future holding reference of buf
and Self
,
which means it can’t be send to another thread
Trait Implementations
sourceimpl AsSs for Instrument
impl AsSs for Instrument
fn as_ss(&self) -> BorrowedSs<'_>
sourceimpl Debug for Instrument
impl Debug for Instrument
sourceimpl FromRawSs for Instrument
impl FromRawSs for Instrument
unsafe fn from_raw_ss(s: RawSs) -> Self
sourceimpl HasAttribute for Instrument
impl HasAttribute for Instrument
sourceimpl Hash for Instrument
impl Hash for Instrument
sourceimpl IntoRawSs for Instrument
impl IntoRawSs for Instrument
fn into_raw_ss(self) -> RawSs
sourceimpl Ord for Instrument
impl Ord for Instrument
sourceimpl PartialEq<Instrument> for Instrument
impl PartialEq<Instrument> for Instrument
sourcefn eq(&self, other: &Instrument) -> bool
fn eq(&self, other: &Instrument) -> bool
This method tests for self
and other
values to be equal, and is used
by ==
. Read more
sourcefn ne(&self, other: &Instrument) -> bool
fn ne(&self, other: &Instrument) -> bool
This method tests for !=
.
sourceimpl PartialOrd<Instrument> for Instrument
impl PartialOrd<Instrument> for Instrument
sourcefn partial_cmp(&self, other: &Instrument) -> Option<Ordering>
fn partial_cmp(&self, other: &Instrument) -> Option<Ordering>
This method returns an ordering between self
and other
values if one exists. Read more
1.0.0 · sourcefn lt(&self, other: &Rhs) -> bool
fn lt(&self, other: &Rhs) -> bool
This method tests less than (for self
and other
) and is used by the <
operator. Read more
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
sourceimpl Read for Instrument
impl Read for Instrument
sourcefn read(&mut self, buf: &mut [u8]) -> Result<usize>
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
Pull some bytes from this source into the specified buffer, returning how many bytes were read. Read more
1.36.0 · sourcefn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
Like read
, except that it reads into a slice of buffers. Read more
sourcefn is_read_vectored(&self) -> bool
fn is_read_vectored(&self) -> bool
can_vector
)Determines if this Read
er has an efficient read_vectored
implementation. Read more
1.0.0 · sourcefn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>
fn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>
Read all bytes until EOF in this source, placing them into buf
. Read more
1.0.0 · sourcefn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
Read all bytes until EOF in this source, appending them to buf
. Read more
1.6.0 · sourcefn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
Read the exact number of bytes required to fill buf
. Read more
sourcefn read_buf(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>
fn read_buf(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>
read_buf
)Pull some bytes from this source into the specified buffer. Read more
sourcefn read_buf_exact(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>
fn read_buf_exact(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>
read_buf
)Read the exact number of bytes required to fill buf
. Read more
1.0.0 · sourcefn by_ref(&mut self) -> &mut Self
fn by_ref(&mut self) -> &mut Self
Creates a “by reference” adaptor for this instance of Read
. Read more
sourceimpl Read for &Instrument
impl Read for &Instrument
sourcefn read(&mut self, buf: &mut [u8]) -> Result<usize>
fn read(&mut self, buf: &mut [u8]) -> Result<usize>
Pull some bytes from this source into the specified buffer, returning how many bytes were read. Read more
1.36.0 · sourcefn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>
Like read
, except that it reads into a slice of buffers. Read more
sourcefn is_read_vectored(&self) -> bool
fn is_read_vectored(&self) -> bool
can_vector
)Determines if this Read
er has an efficient read_vectored
implementation. Read more
1.0.0 · sourcefn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>
fn read_to_end(&mut self, buf: &mut Vec<u8, Global>) -> Result<usize, Error>
Read all bytes until EOF in this source, placing them into buf
. Read more
1.0.0 · sourcefn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>
Read all bytes until EOF in this source, appending them to buf
. Read more
1.6.0 · sourcefn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>
Read the exact number of bytes required to fill buf
. Read more
sourcefn read_buf(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>
fn read_buf(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>
read_buf
)Pull some bytes from this source into the specified buffer. Read more
sourcefn read_buf_exact(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>
fn read_buf_exact(&mut self, buf: &mut ReadBuf<'_>) -> Result<(), Error>
read_buf
)Read the exact number of bytes required to fill buf
. Read more
1.0.0 · sourcefn by_ref(&mut self) -> &mut Self
fn by_ref(&mut self) -> &mut Self
Creates a “by reference” adaptor for this instance of Read
. Read more
sourceimpl Write for Instrument
impl Write for Instrument
sourcefn write(&mut self, buf: &[u8]) -> Result<usize>
fn write(&mut self, buf: &[u8]) -> Result<usize>
Write a buffer into this writer, returning how many bytes were written. Read more
sourcefn flush(&mut self) -> Result<()>
fn flush(&mut self) -> Result<()>
Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
sourcefn is_write_vectored(&self) -> bool
fn is_write_vectored(&self) -> bool
can_vector
)Determines if this Write
r has an efficient write_vectored
implementation. Read more
1.0.0 · sourcefn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
Attempts to write an entire buffer into this writer. Read more
sourcefn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
write_all_vectored
)Attempts to write multiple buffers into this writer. Read more
sourceimpl Write for &Instrument
impl Write for &Instrument
sourcefn write(&mut self, buf: &[u8]) -> Result<usize>
fn write(&mut self, buf: &[u8]) -> Result<usize>
Write a buffer into this writer, returning how many bytes were written. Read more
sourcefn flush(&mut self) -> Result<()>
fn flush(&mut self) -> Result<()>
Flush this output stream, ensuring that all intermediately buffered contents reach their destination. Read more
sourcefn is_write_vectored(&self) -> bool
fn is_write_vectored(&self) -> bool
can_vector
)Determines if this Write
r has an efficient write_vectored
implementation. Read more
1.0.0 · sourcefn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>
Attempts to write an entire buffer into this writer. Read more
sourcefn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>
write_all_vectored
)Attempts to write multiple buffers into this writer. Read more
impl Eq for Instrument
impl StructuralEq for Instrument
impl StructuralPartialEq for Instrument
Auto Trait Implementations
impl RefUnwindSafe for Instrument
impl Send for Instrument
impl Sync for Instrument
impl Unpin for Instrument
impl UnwindSafe for Instrument
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more