Queuing

The queuing mechanism in VISA gives an application the flexibility to receive events only when it requests them. An application uses the viWaitOnEvent() operation to retrieve the event information. However, in addition to retrieving events from the queue, you can also use viWaitOnEvent() in your application to halt the current execution and wait for the event to arrive. Both of these cases are discussed in this section.

The event queuing process requires that you first enable the session to sense the particular event type. When enabled, the session can automatically queue the event occurrences as they happen. A session can later dequeue these events using the viWaitOnEvent() operation. You can set the timeout to VI_TMO_IMMEDIATE if you want your application to check if any event of the specified event type exists in the queue.

Note  Each session has a queue for each of the possible events that can occur. This means that each queue is per session and per event type.

An application can also use viWaitOnEvent() to wait for events if none currently exists in the queue. When you select a non-zero timeout value (something other than VI_TMO_IMMEDIATE), the operation retrieves the specified event if it exists in the queue and returns immediately. Otherwise, the application waits until the specified event occurs or until the timeout expires, whichever occurs first. When an event arrives and causes viWaitOnEvent() to return, the event is not queued for the session on which the wait operation was invoked. However, if any other session is currently enabled for queuing, the event is placed on the queue for that session.

You can use viDisableEvent() to disable event queuing on a session, as discussed in the previous section. After calling viDisableEvent(), no further event occurrences are queued on that session, but event occurrences that were already in the event queue are retained. Your application can use viWaitOnEvent() to dequeue these retained events in the same manner as previously described. The wait operation does not need to have events enabled to work; however, the session must be enabled to detect new events. An application can explicitly clear (flush) the event queue with the viDiscardEvents() operation.

The event queues in VISA do not dynamically grow as new events arrive. The default queue length is 50, but you can change the size of a queue by using the VI_ATTR_MAX_QUEUE_LENGTH template attribute. This attribute specifies the maximum number of events that can be placed in a queue.

Note  If the event queue is full and a new event arrives, the new event is discarded.

VISA does not let you dynamically configure queue lengths. That is, you can only modify the queue length on a given session before the first invocation of the viEnableEvent() operation, as shown in the following code segment.

status = viSetAttribute(instr, VI_ATTR_MAX_QUEUE_LENGTH, 10);
status = viEnableEvent(instr, VI_EVENT_SERVICE_REQ, VI_QUEUE, VI_NULL);

See the handling events example for an example of handling events via the queue mechanism.