op_prg_list_sort()

Abstract

Sorts a list according to a comparison algorithm implemented via a procedure argument.

Note: This KP is a macro call included for backward compatibility only. Use prg_list_sort() in new code.

Syntax

op_prg_list_sort (list_ptr, compare_proc)
Argument Type Description
ist_ptr List* pointer to the list-of-interest [A pointer to a list can be obtained from several KPs: an empty list can be obtained from op_prg_list_create(); a list representing the contents of a file can be obtained from op_prg_gdf_read(); a list can be allocated by user code, and initialized via op_prg_list_init().]
compare_proc Procedure pointer to a C procedure used to perform element comparison [Comparison procedures can be defined in process model function blocks, or external C files. If the KP op_prg_list_sort() is being invoked from a process model executive or transition statement, a pointer to a comparison procedure can be obtained by referencing the procedure’s name, provided that a declaration of the procedure appears in the header block or temporary variable block of the process model. If op_prg_list_sort() is being invoked from an external C file, a pointer to a comparison procedure can be obtained the same way, provided that a declaration of the procedure appears in the file before the invocation.]

Return Type

void

No return value.

Example

The list to be sorted contains data structure elements (struct pair); the pair structure contains two integer fields (x & y); sort the list so that the sum of the fields is largest near the list head.

/* comparison procedure definition: */
sum_compare (struct pair *aptr, struct pair *bptr)
    {
    int asum, bsum;

    asum = aptr->x + aptr->y;
    bsum = bptr->x + bptr->y;

    if (asum > bsum)         return  1;
    else if (asum < bsum)    return -1;
    else	                         return  0;
    }

/* sort KP invocation */
op_prg_list_sort (list_ptr, sum_compare);

Details

This KP sorts a list by sub-dividing it and recursively sorting the list segments. The sorting order of elements is determined using a comparison procedure which is user-defined. This interface provides flexibility in the sorting metric, since arbitrary computations can be performed in the comparison procedure.

The comparison procedure must accept two arguments (A & B) that are both pointers to the type of data structure or simple data type elements stored in the list-of-interest. The comparison procedure returns an integer code which indicates the precedence relationship between the two elements. The integer code takes on the following values:

1 indicates that A should be closer to the list head than B
-1 indicates that B should be closer to the list head than A
0 indicates that A and B are equal in rank

Two example comparison procedure declarations are shown below:

int
comp_proc1 (Packet *aptr, Packet *bptr)


int
comp_proc2 (char *aptr, char *bptr)

Note: This KP 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 sort a list according to a user-defined metric. This is useful for organizing lists whose elements should be processed in an order that depends on their contents. For example the elements may represent requests that each have a priority value; sorting the list is therefore an operation that should be performed before processing begins, so that the higher priority requests can be accessed first.

Errors

  • Program Abort: Segmentation violation (due to invalid list pointer or malformed list).
  • Program Abort: Segmentation violation/Bus error (due to an invalid compare_proc argument or coding error within the comparator procedure).

Reference

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · 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