op_prg_list_create()
Abstract
Allocates a new, empty list.
Note: This KP is a macro call included for backward compatibility only. Use prg_list_create() in new code.
Syntax
op_prg_list_create ()
| Argument | Type | Description |
|---|---|---|
| no arguments |
Return Type
List*
Pointer to the newly created empty list. This list pointer is usually directly assigned to a variable declared as a List*, as shown in the Example section.]
Example
/* allocate an empty list */
lptr = op_prg_list_create ();
/* allocate four parameter block data structures, and insert into list */
temp_ptr = op_prg_mem_alloc (sizeof (struct parm_block));
op_prg_list_insert (lptr, temp_ptr, OPC_LISTPOS_TAIL);
temp_ptr = op_prg_mem_alloc (sizeof (struct parm_block));
op_prg_list_insert (lptr, temp_ptr, OPC_LISTPOS_TAIL);
temp_ptr = op_prg_mem_alloc (sizeof (struct parm_block));
op_prg_list_insert (lptr, temp_ptr, OPC_LISTPOS_TAIL);
temp_ptr = op_prg_mem_alloc (sizeof (struct parm_block));
op_prg_list_insert (lptr, temp_ptr, OPC_LISTPOS_TAIL);
Details
An empty list has no elements contained within it. However, it is ready for elements to be inserted, via the KP op_prg_list_insert(). Elements can be added to the list in any order.
Purpose
Provides a mechanism to obtain a completely fresh list allocated by the Simulation Kernel. This is one of two ways to obtain an empty list; the other way is for user code to allocate a list (either by a statically-allocated variable, or within a dynamically-allocated data structure), and to initialize the list via the KP op_prg_list_init().
Errors
- Program Abort: Allocation of memory failed. Unable to create list data structure.
Reference
- Use the KP op_prg_list_insert() to insert an element into a list
- Use the KP op_prg_list_free() to remove and deallocate all elements on a list (retaining the list itself)
- Use the KP op_prg_mem_free() to deallocate a list which is no longer useful (after freeing its elements)
- Use the KP op_prg_list_init() to initialize a list which was dynamically allocated, before the list is used