op_sar_segbuf_pk_insert()
Abstract
Inserts the specified source packet at the tail of the specified segmentation buffer. The user-defined label argument “tags” the packet for later references.
Syntax
op_sar_segbuf_pk_insert (sb_hndl, src_pkptr, src_pk_label)
| Argument | Type | Description |
|---|---|---|
sb_hndl |
Sbhandle |
handle identifying the segmentation buffer-of-interest [This value must identify a Sar segmentation buffer. A Sar buffer handle is obtained when a buffer is created via the KP op_sar_buf_create().] |
src_pkptr |
Packet* |
pointer to the source packet to be inserted into the buffer [A pointer to a packet can be obtained from many KPs, including op_pk_create(), op_pk_create_fmt(), op_pk_copy(), op_pk_get(), op_subq_pk_access(), and op_subq_pk_remove().] |
src_pk_label |
OpT_Int64 |
label for the specified source packet [A source packet label is a user-defined numeric value that “tags” the specified source packet; the label is thus associated with the contents of the specified source packet in any of its derived Sar segments. A source packet label can be passed to the KP op_sar_rsgbuf_lbl_pk_range_get() to determine the range of bits stored in a Sar resegmentation buffer associated with the specified source packet.] |
Return Type
void
No return value.
Example
/* Obtain an arriving source packet. */
src_pkptr = op_pk_get (HLP_INSTRM);
/* Determine the size of the source packet. */
rem_size = op_pk_total_size_get (src_pkptr);
/* Insert the source packet into segmentation buffer. */
op_sar_segbuf_pk_insert (seg_sbh, src_pkptr, pk_seq_num++);
/* Remove and send the first segment associated with arriving packet. */
seg_pkptr = op_sar_srcbuf_seg_remove (rsm_sbh, SEG_SIZE);
op_pk_send (seg_pkptr, LLP_OUTSTRM);
/* Compute new remainder of source packet */
rem_size -= SEG_SIZE;
/* If there is a remainder of source packet, schedule next segment transmission. */
if (rem_size > 0)
op_intrpt_schedule_self (op_sim_time () + SEG_TX_TIME, SEG_TX_CODE);
Details
The src_pk_label argument is used to identify the bits associated with the inserted source packet. Every bit from the inserted source packet is associated with the specified label, so if the source packet is split into several Sar segments, the bits associated with the source packet in each resulting segment will be identifiable through their source packet label. The label of a source packet can later be used to identify the segment for flushing from a resegmentation buffer via the KPs op_sar_rsgbuf_lbl_seg_range_get() and op_sar_srcbuf_bits_flush(). Source packet labels are user-defined numeric values to support the use of process-model specific sequence numbers as labels. Typically, source packets are either labeled with a packet sequence number, or with a sequence number based on the first (or last) byte (or bit) that they contain.
Note that once a source packet has been inserted into a segmentation buffer, it can no longer be accessed through its original pointer (i.e., no further packet operations can be performed on the packet pointer). The only way to regain access to the packet is to remove its segments from the segmentation buffer, insert them into a reassembly buffer, and then extract the completely reassembled source packet. The reassembled packet is a “recreation” of the original packet, and may have a pointer value and ID different than the original packet.
Purpose
Provides a mechanism for inserting a source packet into a segmentation buffer (note that there are no alternate techniques for inserting packets into a segmentation buffer). Segmentation buffers split or merge source packets into segments of user-requested size; the actual act of creating segments occurs at the invocation of the KPs op_sar_srcbuf_seg_remove() or op_sar_srcbuf_seg_access(). Segmentation buffers will accept the insertion of “normal” packets (i.e., packets that have not been segmented by the Sar package); they will also accept the insertion of Sar segments, which are treated as source packets and split or merged into another “level” of segments (final reassembly of source packets that have been hierarchically segmented requires sequential processing by a series of reassembly buffers).
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 (segmentation). - Program Abort: Packet pointer references unowned packet (
<pkid>) - Program Abort: Packet pointer references static packet (
<pkid>) - Program Abort: Packet (
<pkid>) is already segmented. / It may not be inserted into another segmentation buffer. - Program Abort: Virtual memory limits exceeded. Too many allocated objects.
- Recoverable Error: Allocation of object block failed / Object type (
<ob_type>).
Reference
- Use the KP op_sar_srcbuf_seg_remove() to remove a Sar segment from the head of a (re)segmentation buffer
- Use the KP op_sar_srcbuf_seg_access() to copy a Sar segment from the head of a (re)segmentation buffer
- Use the KP op_sar_srcbuf_bits_flush() to flush a bit-range, identified by local bit index and length, from a (re)segmentation buffer
- Use the KP op_sar_buf_size() to determine the number of bits stored in a Sar buffer