quanser.hardware.task.set_buffer_overflow_mode

navigation bar

Sets the buffer overflow mode for a task.

Syntax

err = task.set_buffer_overflow_mode(mode)

Description

This method determines how buffer overflows are handled by a task. The task buffer overflows when samples are not being read fast enough by hil_task_read_xxx to keep up with the data being read by the card at its inputs, or when samples are not being written fast enough by hil_task_write_xxx to stay ahead of the data being written by the card to its outputs. Buffering is used to handle cases where the application is momentarily interrupted and the size of the buffer determines how long an interruption is permitted. If increasing the buffer size does not prevent buffer overflow then the application is simply not capable of keeping up with real time.

By default, an error will be returned by the next hil_task_read_xxx or hil_task_write_xxx call when a buffer overflow occurs and the task will need to be stopped. The reason this is the default behaviour is that the HIL API is intended for real-time applications where missing samples is regarded as a fatal error.

However, for those applications where samples may be missed then the buffer overflow handling can be altered using the hil_task_set_buffer_overflow_mode function (if the card supports it). There are three possible modes:

BUFFER_MODE_ERROR_ON_OVERFLOW (0): This is the default mode in which buffer overflows cause a QERR_BUFFER_OVERFLOW error to be returned by the next hil_task_read_xxx or hil_task_write_xxx. The task should be stopped at that point.
BUFFER_MODE_OVERWRITE_ON_OVERFLOW (1): In this mode, old samples in the buffer are discarded to make room for new samples if the buffer overflows. For writer tasks, this means that there may be unexpected discontinuities in the output waveforms. For reader tasks, it means that samples may be lost and only the more recent samples will be read.
BUFFER_MODE_DISCARD_ON_OVERFLOW (2): In this mode, new samples are discarded if there is no room in the buffer. For writer tasks, this means that there may be unexpected discontinuities in the output waveforms. For reader tasks, it means that samples may be lost and only the oldest samples will be read.
BUFFER_MODE_WAIT_ON_OVERFLOW (3): In this mode, the task waits on buffer overflow for space to become available. This mode is not supported by hardware cards but is only for use by simulated cards.
BUFFER_MODE_SYNCHRONIZE (4): In this mode, the task provides complete buffer synchronization. This mode is not supported by hardware cards but is only for use by simulated cards.

If no err output is provided then it throws an exception if an error occurs. In generated code it prints the error message. Use hil_get_error_message to get the message associated with an error code.

Parameters

task

Task handle returned by one of the hil_task_create functions.

mode

The buffer overflow mode. The mode is either one of the t_buffer_overflow_mode enumeration values or an integer scalar representing the mode.

Outputs

err

A negative error code or zero on success.

Examples

% Sets the buffer overflow mode to BUFFER_MODE_OVERWRITE_ON_OVERFLOW
hil_task_set_buffer_overflow_mode(task, t_buffer_overflow_mode.BUFFER_MODE_OVERWRITE_ON_OVERFLOW);