dag_get_stream_poll(3)

NAME
dag_get_stream_poll - retrieve the parameters that describe the polling behaviour of a stream

SYNOPSIS
#include "dagapi.h "

int
dag_get_stream_poll(int dagfd, int stream_num, uint32_t* mindata, struct timeval* maxwait, struct timeval* poll);

DESCRIPTION
The DAG drivers avoid the overhead of interrupts by polling instead. The amount of data that must be received before a call to dag_advance_stream(3) or dag_rx_stream_next_record(3) will return is given by mindata. This defaults to 16 bytes, the size of an ERF record header. If mindata is zero, the receive functions will return immediately if no data is available, allowing non-blocking behaviour.

maxwait is the maximum amount of time the receive functions should wait before returning. This overrides the mindata parameter, so that even if mindata is non-zero, the call will return with 0 bytes available after maxwait time. By default the maxwait parameter is set to the special value zero which means that it is disabled. This means that the receive calls will block indefinitely for mindata bytes. If mindata bytes are not available when the receive function is first called, the library will sleep for poll time before checking for more data. This sleep avoids excessive polling traffic to the DAG card that may waste bus bandwidth, and frees the CPU for other processes. Each time the library wakes from a poll sleep, the timeout as set by maxwait is checked, and the function will return if maxwait is exceeded. The default value of poll is 10ms, implying a maximum of 100 polls per second when no data is available. The value of poll should always be less than or equal to the value of maxwait, as the minimum sleep time is poll. The poll sleep is implemented in user space using the POSIX.1b nanosleep(2) function. The current implementation of this call in Linux is based on the normal kernel timer mechanism, which has a resolution of 1/HZ, or 10ms on Linux/i386. This means that values of maxwait and poll less than 10ms will result in additional delay up to 10ms.

If the application uses a real time scheduler such as SCHED_FIFO or SCHED_RR, then sleep values up to 2ms will be performed as busy-waits. This allows for faster and more accurate polling, but will lead to high CPU utilization due to busy-waiting rather than releasing the CPU to the scheduler.

RETURN VALUE
On success dag_get_stream_poll returns zero, otherwise it returns -1 with errno set appropriately.

ERRORS

EBADF
    dagfd is an invalid file descriptor.

EINVAL
    stream_num refers to a stream that has not been attached.

NOTES
dag_get_stream_poll obsoletes dag_getpollparams(3).

EXAMPLE
FIXME Sample code.

SEE ALSO
dag_advance_stream(3), dag_attach_stream(3), dag_detach_stream(3), dag_get_stream_buffer_level(3), dag_get_stream_buffer_size(3), dag_rx_get_stream_count(3), dag_rx_stream_next_inline(3), dag_rx_stream_next_record(3), dag_set_stream_poll(3), dag_start_stream(3), dag_stop_stream(3).

BUGS
Report bugs to <support@endace.com>.

LAST UPDATED
$Author: koryn $
$Revision: 2474 $
$Date: 2005-11-10 11:13:19 +1300 (Thu, 10 Nov 2005) $

COPYRIGHT
(c) 2004-2005 Endace Technology, Hamilton, New Zealand. All Rights Reserved.