prg_list_insert()

Abstract

Inserts a data element into a list at a position specified by index.

Syntax

prg_list_insert (list_ptr, element_ptr, pos_index)
Argument Type Description
list_ptr PrgT_List* pointer to the list-of-interest.
A pointer to a list can be obtained from several functions: an empty list can be obtained from prg_list_create(); a list representing the contents of a file can be obtained from prg_gdf_read(); a list can be allocated by user code and initialized via prg_list_init().
element_ptr Vartype* pointer to the element to be inserted.
Any data types can be elements of a list, including simple data types (such as integers or character strings) and complex data structures. Casting of the element pointer is not necessary (note that Vartype* is not a real data type, but a notational convention).
pos_index int numeric position index of the element to be inserted into the list.
Position indices start at 0 at the head, incrementing by one until the tail is reached. You can specify either an explicit numeric position index or the symbolic constants (PRGC_LISTPOS_HEAD or PRGC_LISTPOS_TAIL.)

Return Type

Prg_List_Cell *

The list cell containing the inserted element.

prg_list_funcs.h

Example:

/* allocate a list */
list_ptr = (PrgT_List *) prg_mem_alloc (sizeof (PrgT_List));

/* initialize a list */
prg_list_init (list_ptr);

/** move the contents of subqueue #0 into the list **/

/* determine the number of packets in the subqueue */
subq_size = op_subq_stat (0, OPC_QSTAT_PKSIZE);

for (i = 0; i < subq_size; i++)
	{
	/* take a single packet from the subqueue head */
	pkptr = op_subq_pk_remove (0, OPC_QPOS_HEAD);

	/* insert the packet onto the list tail */
	prg_list_insert (list_ptr, pkptr, PRGC_LISTPOS_TAIL);
	}

Details

Elements can be inserted into a list in any order, using the pos_index argument to position the insertion. As elements are inserted in a list at positions other than the list tail, elements between the insertion point and the tail will have their position indices shifted up by one.

The special symbolic list positions PRGC_LISTPOS_HEAD and PRGC_LISTPOS_TAIL can be used to insert elements at the head or the tail of the list. It is recommended that these constants be used whenever possible.

This function does not guard against redundant insertions of elements into the list. In other words, the same element address is allowed to be present at multiple locations in the list.

WARNING: This function is MT unsafe, as described in “Multi-Threading Safety“ on page 11. Access to shared lists must be externally serialized.

Purpose:

Provides a mechanism to insert elements into a list. Lists are typically constructed to hold textual information (such as routing or address translation tables), or to hold a set of packets stored temporarily in a processor.

Errors:

  • Program Abort: Segmentation violation. (due to an illegal list pointer or malformed list)

Reference:

  • use prg_list_remove() to remove an element from a list
  • use prg_list_create() to have the Programming support library allocate a new, empty list
  • use prg_list_init() to prepare a new, empty list which has been allocated by user code
  • use prg_list_free() to remove and deallocate all elements on a list (retaining the list itself)

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com