prg_list_free()
摘要
释放指定列表的内容,将关联的内存资源释放出来供其他用途使用。
语法
prg_list_free (list_ptr)
| 参数 | 类型 | 说明 |
|---|---|---|
list_ptr |
PrgT_List* |
指向目标列表的指针。 获取列表指针的途径有多种:空列表可由 prg_list_create() 获得;表示文件内容的列表可由 prg_gdf_read() 获得;也可以由用户代码静态分配列表并通过 prg_list_init() 初始化。 |
返回类型
void
无返回值。
头文件
prg_list_funcs.h
示例:
/* 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);
详情
通过 prg_list_free() 释放列表的内容并不会释放列表本身(列表由一个小型数据结构表示)。列表会被重新初始化并准备好供再次使用。如果列表本身不再需要,可以使用 prg_mem_free() 将其释放。
该函数只能释放通过 Program Library 已知方法分配的列表元素。例如,直接通过内存分配器 malloc() 分配的元素不会被释放,并且会发出错误消息。Program Library 已知的方法包括通过 prg_mem_alloc()、prg_gdf_read()、prg_str_decomp() 和 prg_list_elems_copy() 分配的内存。要释放以其他方式分配的元素,请使用 prg_list_clear()。
**警告:**该函数 MT 不安全(线程不安全),相关说明见“Multi-Threading Safety“ 第 11 页。对共享列表的访问必须由外部串行化。
用途:
当列表中的所有元素不再有用时将其释放,从而释放内存。这些元素必须是通过已知的 Program Library 接口分配的。
错误:
- 程序中止:段违例。(由于列表中存在未知内存类型或非法元素指针)
- 程序中止:总线错误。(由于列表中存在未知内存类型或非法元素指针)
- 诊断错误:无法释放未知内存类型。
参考:
- 使用
prg_list_clear()仅移除列表元素而不释放它们,或使用自定义释放例程移除并释放元素 - 使用
prg_mem_free()在释放列表元素之后释放不再有用的列表 - 使用
prg_list_create()分配一个新的空列表 - 使用
prg_list_init()准备一个新的空列表,或将现有列表重置为空状态