op_sar_rsmbuf_pk_flush()
Abstract
Flushes all incomplete source packets from the specified reassembly buffer that have been in the buffer longer than the specified time limit.
Syntax
op_sar_rsmbuf_pk_flush (sb_hndl, flush_time)
| Argument | Type | Description |
|---|---|---|
sb_hndl |
Sbhandle |
handle identifying the reassembly buffer-of-interest [This value must identify a Sar reassembly buffer. A Sar buffer handle is obtained when a buffer is created via the KP op_sar_buf_create().] |
flush_time |
double |
time limit for flushing incomplete source packets [This value specifies the time limit (in seconds) used to determine which incomplete source packets in the specified reassembly buffer will be flushed: incomplete packets stored in the buffer for equal or longer durations than this limit will be flushed, and incomplete source packets stored for shorter durations will be kept in the buffer. Setting this argument to 0.0 will cause all incomplete source packets to be flushed.] |
Return Type
void
No return value.
Example
/* Obtain a segment from input stream. */
seg_pkptr = op_pk_get (SEG_INSTRM);
/* Determine the size of the segment. */
seg_size = op_pk_total_size_get (seg_pkptr);
/* Loop from 3 minutes to 20 seconds, successively reducing the flush time */
/* and flushing the reassembly buffer of packets older than this time. Stop */
/* when the buffer is less than threshold value for adding new segment. */
for (ft = 180.0, buf_overflow = 0; ((pksize + op_sar_buf_size (rsm_sbh))
> MAX_RSM_BUF_SIZE); ft -= 20.0)
{
if (ft == 0.0) { buf_overflow = 1; break; }
/* Flush buffer using current iteration of flush time. */
op_sar_rsmbuf_pk_flush (rsm_sbh, ft);
}
/* Insert segment into reassembly buffer if buffer overflow has not occurred. */
if (!buf_overflow)
op_sar_rsmbuf_seg_insert (rsm_sbh, seg_pkptr);
Details
There are three methods by which a reassembly buffer can be flushed of incomplete source packets:
- through invocation of this KP
- through the timed flush buffer option
- through the automatic flush buffer option
These three methods can all be used on the same reassembly buffer, without interfering with each other. The methods are differentiated in the following points:
- op_sar_rsmbuf_pk_flush() flushes incomplete source packets that have been stored in the specified buffer for a duration longer than or equal to a specified time limit; this KP performs an immediate flush action when invoked, and has no continuing effect on the buffer after returning.
- the timed flush buffer option flushes incomplete source packets that have been stored in the affected buffer longer than a specified time limit; this option is a continuing mode of a buffer, and it performs flush actions when they first become necessary, based on internally-scheduled events derived from the times of first-segment insertion for each incomplete packet.
- the automatic flush buffer option flushes incomplete source packets that have a bit sequence gap (i.e., bit <N> is present, but bit <N-1> is not); this option is a continuing mode of a buffer, and it performs flush actions when they first become necessary, upon the insertion of a Sar segment that indicates a bit sequence gap.
This KP has no effect on complete source packets stored in the specified reassembly buffer, regardless of how long they have been present in the buffer.
Purpose
Provides a mechanism to flush old, incomplete source packets from a reassembly buffer. Flushing of incomplete source packets may be necessary if the reassembly buffer obtains Sar segments from a non-reliable communications channel (e.g., a mobile radio environment with highly dynamic link statuses). In such cases, link failures may prohibit required Sar segments from ever arriving at a destination node containing a reassembly buffer, leading to permanently incomplete source packets in the buffer. If repeated many times, this failure mode would leave a reassembly buffer with large quantities of such incomplete source packets, a negative outcome both in terms of modeled system resources and simulation memory usage. Thus, this KP proves useful to flush incomplete packets that are older than a specified time limit from a reassembly buffer.
Errors
- Standard Sar errors (see Table 15)
- Program Abort: Buffer handle references destroyed buffer.
- Program Abort: Buffer type (
<type>) is invalid for this KP, should be (reassembly). - Recoverable Error: Flush time (
<flush_time>) is invalid. / Value must be greater than or equal to 0.0.
Reference
- Use the KP op_sar_buf_options_set() to set flush-oriented options on a reassembly buffer
- Use the KP op_sar_buf_size() to determine the number of bits stored in a Sar buffer
- Use the KP op_sar_rsmbuf_pk_remove() to remove and obtain a complete source packet from the head of a reassembly buffer
- Use the KP op_sar_rsmbuf_seg_insert() to insert a Sar segment into a reassembly buffer