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
- Use the KP op_prg_list_insert() to insert new elements in a list