prg_list_free()

Abstract

Deallocates the contents of the specified list, releasing associated memory resources for other purposes.

Syntax

prg_list_free (list_ptr)
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 statically allocated by user code and initialized via prg_list_init().

Return Type

void

No return value.

prg_list_funcs.h

Example:

/* open and read in the contents of a GDF */
list_ptr = prg_gdf_read (gdf_file_name);

/* loop through the contents of the GDF contents list, */
/* printing each line */
list_size = prg_list_size (list_ptr);
for (i = 0; i < list_size; i++)
	printf ("line %d: [%s]\n", i, (char*) prg_list_access (list_ptr, i));

/* deallocate the elements on the list */
prg_list_free (list_ptr);

/* deallocate the list itself */
prg_mem_free (list_ptr);

Details

Deallocating the contents of a list via prg_list_free() does not deallocate the list itself (a list is represented by a small data structure). Instead, the list is initialized and made ready for reuse. If the list itself is no longer needed, it can be deallocated using prg_mem_free().

This function is capable of deallocating only list elements that have been allocated via methods that are known to the Program Library. For example, elements that are allocated directly via the memory allocator malloc() will not be deallocated and an error message will be issued. Methods that are known to the Program Library include memory allocated via prg_mem_alloc(), prg_gdf_read(), prg_str_decomp(), and prg_list_elems_copy(). To deallocate elements that were allocated by another method, use prg_list_clear().

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

Purpose:

Deallocates all the elements in a list when they are no longer useful, releasing memory. The elements must have been allocated via known Program Library interfaces.

Errors:

  • Program Abort: Segmentation violation. (due to the presence in the list of unknown memory types or illegal element pointers)
  • Program Abort: Bus Error. (due to the presence in the list of unknown memory types or illegal element pointers)
  • Diagnostic Error: Unable to deallocate unknown memory type.

Reference:

  • use prg_list_clear() to simply remove list elements without deallocating them, or to remove and deallocate elements using a custom deallocation routine
  • use prg_mem_free() to deallocate a list that is no longer useful, after freeing its elements
  • use prg_list_create() to allocate a new, empty list
  • use prg_list_init() to prepare a new, empty list or reset an existing list to an empty state

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