GetStreamTCPReceiveBufferStatus [LJM User's Guide]

Requires LJM 1.2000 or later

For handles running stream over the network, gets the current state of the receive buffer.

Syntax

LJM_ERROR_RETURN LJM_GetStreamTCPReceiveBufferStatus(
int Handle,
unsigned int * ReceiveBufferBytesSize,
unsigned int * ReceiveBufferBytesBacklog)

Parameters

Handle [in]

A device handle. The handle is a connection ID for an active device. Generate a handle with LJM_Open or LJM_OpenS.

ReceiveBufferBytesSize [out]

Returns the current maximum number of bytes that can be stored in the receive buffer before it is full.

ReceiveBufferBytesBacklog [out]

Returns the current number of bytes stored in the receive buffer.

Returns

LJM errorcodes or 0 for no error.

Remarks

Before calling this function, start stream using LJM_eStreamStart.

If the device handle's connection type is Ethernet or WiFi, this function should be called after LJM_eStreamRead if auto-recovery is occurring.

If the device handle's connection type is USB, this function returns meaningless values.

Use LJM_GetHandleInfo to get the handle's connection type.

If the ratio of ReceiveBufferBytesBacklog / ReceiveBufferBytesSize is consistently increasing, auto-recovery is likely to happen. If the ReceiveBufferBytesBacklog is staying relatively low but auto-recovery is still occurring, there may be network reliability issues or other issues. In either case, see strategies for reducing auto-recovery.

The Receive Buffer

All TCP streams have a receive buffer. In the context of receiving stream data from a LabJack device, the receive buffer is a buffer on the host computer that is managed by the operating system. The LabJack device sends packets to this buffer, which LJM then reads from.

As the receive buffer fills up with bytes, the host computer will report to the LabJack device that it has a reduced receive window. For example, if there are 1040 bytes of free space remaining in the computer's receive buffer, TCP protocol will report to the device that the computer has a receive window of 1040. The device will then be able to send 1040 bytes and no more until the computer sends another packet declaring that it has freed some space from the receive buffer.

Once the receive window is completely full, the LabJack device is temporarily not able to send more packets. Once this happens, it begins filling its own device scan buffer. Once the device scan buffer is completely full, it will stop collecting scans and auto-recovery will occur.

During stream, LJM has a dedicated thread that does nothing but read from the receive window. This usually prevents the receive window from being completely filled, but some computers may be, in effect, slower than the LabJack device—such that the device sends bytes faster than the host computer reads bytes from the receive window. For this reason, it is important to monitor the state of the receive buffer if auto-recovery is occurring.