3. Iterators

So-called iterators are a code pattern to retrieve various data from libcgroup in distinct chunks, for example when an application needs to read list of groups in a hierarchy, it uses iterator to get one group at a time. More...

Data Structures
struct	cgroup_file_info
	Information about found directory (= a control group). More...
struct	cgroup_stat
	One item in stats file. More...
struct	cgroup_mount_point
	Information about mounted controller. More...
struct	controller_data
	Detailed information about available controller. More...
Walk through control group filesystem
This iterator returns all subgroups of given control group. It can be used to return all groups in given hierarchy, when root control group is provided.
enum	cgroup_walk_type { CGROUP_WALK_TYPE_PRE_DIR = 0x1, CGROUP_WALK_TYPE_POST_DIR = 0x2 }
	Type of the walk. More...
enum	cgroup_file_type { CGROUP_FILE_TYPE_FILE, CGROUP_FILE_TYPE_DIR, CGROUP_FILE_TYPE_OTHER }
	Type of returned entity. More...
int	cgroup_walk_tree_begin (const char *controller, const char *base_path, int depth, void **handle, struct cgroup_file_info *info, int *base_level)
	Walk through the directory tree for the specified controller.
int	cgroup_walk_tree_next (int depth, void **handle, struct cgroup_file_info *info, int base_level)
	Get the next directory in the walk.
int	cgroup_walk_tree_end (void **handle)
	Release the iterator.
int	cgroup_walk_tree_set_flags (void **handle, int flags)
	Set the flags for walk_tree.
Read group stats
libcgroup's cgroup_get_value_string() reads only relatively short parametrs of a group. Use following functions to read stats parameter, which can be quite long.
int	cgroup_read_stats_begin (const char *controller, const char *path, void **handle, struct cgroup_stat *stat)
	Read the statistics values (= stats parameter) for the specified controller and control group.
int	cgroup_read_stats_next (void **handle, struct cgroup_stat *stat)
	Read the next stat value.
int	cgroup_read_stats_end (void **handle)
	Release the iterator.
#define	CG_VALUE_MAX   100
	Maximum length of a value in stats file.
List all tasks in a group
Use following functions to read tasks file of a group.
int	cgroup_get_task_begin (const char *cgroup, const char *controller, void **handle, pid_t *pid)
	Read the tasks file to get the list of tasks in a cgroup.
int	cgroup_get_task_next (void **handle, pid_t *pid)
	Read the next task value.
int	cgroup_get_task_end (void **handle)
	Release the iterator.
List mounted controllers
Use following function to list mounted controllers and to see, how they are mounted together in hierarchies. Use cgroup_get_all_controller_begin() (see later) to list all controllers, including those which are not mounted.
int	cgroup_get_controller_begin (void **handle, struct cgroup_mount_point *info)
	Read the mount table to give a list where each controller is mounted.
int	cgroup_get_controller_next (void **handle, struct cgroup_mount_point *info)
	Read the next mounted controller.
int	cgroup_get_controller_end (void **handle)
	Release the iterator.
List all controllers
Use following functions to list all controllers, including those which are not mounted. The controllers are returned in the same order as in /proc/cgroups file, i.e. mostly random.
int	cgroup_get_all_controller_begin (void **handle, struct controller_data *info)
	Read the first of controllers from /proc/cgroups.
int	cgroup_get_all_controller_next (void **handle, struct controller_data *info)
	Read next controllers from /proc/cgroups.
int	cgroup_get_all_controller_end (void **handle)
	Release the iterator.

---

Detailed Description

So-called iterators are a code pattern to retrieve various data from libcgroup in distinct chunks, for example when an application needs to read list of groups in a hierarchy, it uses iterator to get one group at a time.

Iterator is opaque to the application, the application sees only void* handle pointer, which is managed internally by libcgroup. Each iterator provides at least these functions:

• int iterator_name_begin(void **handle, my_type *item)
  • Initialize the iterator, store pointer to it into the handle.
  • Return the first element in the iterator, let's say it's my_type.
  • Return 0, if the operation succeeded.
  • Return ECGEOF, if the operation succeeded, but the iterator is empty. The value of item is undefined in this case.
  • Return any other error code on error.
• int iterator_name_next(void **handle, my_type *item)
  • Advance to next element in the iterator and return it.
  • Return 0, if the operation succeeded.
  • Return ECGEOF, if there is no item to advance to, i.e. the iterator is already at its end. The value of item is undefined in this case.
  • Return any other error code on error.
• void iterator_name_end(void **handle)
  • Free any data associated with the iterator. This function must be called even when iterator_name_begin() fails.

Todo:

not all iterators follow this pattern, e.g. cgroup_walk_tree_begin() can result both in a state that cgroup_walk_tree_end() is not needed and will sigsegv and in a state that cgroup_walk_tree_end() is needed to free allocated memory. Complete review is needed!

Example of iterator usage:

 void *handle; // our iterator handle
 my_type item; // the data returned by the iterator
 int ret;
 ret = iterator_name_begin(&handle, &item);
 while (ret == 0) {
        // process the item here
        ret = iterator_name_begin(&handle, &item);
 }
 if (ret != ECGEOF) {
        // process the error here
 }
 iterator_name_end(&handle);

---

Define Documentation

#define CG_VALUE_MAX   100

Maximum length of a value in stats file.

---

Enumeration Type Documentation

enum cgroup_file_type

Type of returned entity.

Enumerator:

CGROUP_FILE_TYPE_FILE	File.
CGROUP_FILE_TYPE_DIR	Directory.
CGROUP_FILE_TYPE_OTHER	Directory. Todo: really?

enum cgroup_walk_type

Type of the walk.

Enumerator:

CGROUP_WALK_TYPE_PRE_DIR	Pre-order directory walk, return a directory first and then its subdirectories. E.g. directories would be returned in this order: / /group /group/subgroup1 /group/subgroup1/subsubgroup /group/subgroup2
CGROUP_WALK_TYPE_POST_DIR	Post-order directory walk, return subdirectories of a directory first and then the directory itself. E.g. directories would be returned in this order: /group/subgroup1/subsubgroup /group/subgroup1 /group/subgroup2 /group /

---

Function Documentation

int cgroup_get_all_controller_begin	(	void **	handle,
		struct controller_data *	info
	)

Read the first of controllers from /proc/cgroups.

Parameters:

	handle	Handle to be used for iteration.
	info	The structure which will be filled with controller data.

int cgroup_get_all_controller_end

(

void **

handle

)

Release the iterator.

int cgroup_get_all_controller_next	(	void **	handle,
		struct controller_data *	info
	)

Read next controllers from /proc/cgroups.

Parameters:

	handle	Handle to be used for iteration.
	info	The structure which will be filled with controller data.

int cgroup_get_controller_begin	(	void **	handle,
		struct cgroup_mount_point *	info
	)

Read the mount table to give a list where each controller is mounted.

Parameters:

	handle	Handle to be used for iteration.
	info	The variable where the path to the controller is stored.

Returns:

ECGEOF when no controllers are mounted.

int cgroup_get_controller_end

(

void **

handle

)

Release the iterator.

int cgroup_get_controller_next	(	void **	handle,
		struct cgroup_mount_point *	info
	)

Read the next mounted controller.

While walking through the mount table, the controllers are returned in order of their mount points, i.e. controllers mounted together in one hierarchy are returned next to each other.

Parameters:

	handle	Handle to be used for iteration.
	info	The variable where the path to the controller is stored.

Returns:

ECGEOF when all controllers were already returned.

int cgroup_get_task_begin	(	const char *	cgroup,
		const char *	controller,
		void **	handle,
		pid_t *	pid
	)

Read the tasks file to get the list of tasks in a cgroup.

Parameters:

	cgroup	Name of the cgroup.
	controller	Name of the cgroup subsystem.
	handle	Handle to be used in the iteration.
	pid	The pid read from the tasks file.

Returns:

ECGEOF when the group does not contain any tasks.

int cgroup_get_task_end

(

void **

handle

)

Release the iterator.

int cgroup_get_task_next	(	void **	handle,
		pid_t *	pid
	)

Read the next task value.

Parameters:

	handle	The handle used for iterating.
	pid	The variable where the value will be stored.

Returns:

ECGEOF when the iterator finishes getting the list of tasks.

int cgroup_read_stats_begin	(	const char *	controller,
		const char *	path,
		void **	handle,
		struct cgroup_stat *	stat
	)

Read the statistics values (= stats parameter) for the specified controller and control group.

One line is returned per cgroup_read_stats_begin() and cgroup_read_stats_next() call.

Parameters:

	controller	Name of the controller for which stats are requested.
	path	Path to control group, relative to hierarchy root.
	handle	Handle to be used during iteration.
	stat	Returned first item in the stats file.

Returns:

ECGEOF when the stats file is empty.

int cgroup_read_stats_end

(

void **

handle

)

Release the iterator.

int cgroup_read_stats_next	(	void **	handle,
		struct cgroup_stat *	stat
	)

Read the next stat value.

Parameters:

	handle	Handle to be used during iteration.
	stat	Returned next item in the stats file.

Returns:

ECGEOF when the iterator finishes getting the list of stats.

int cgroup_walk_tree_begin	(	const char *	controller,
		const char *	base_path,
		int	depth,
		void **	handle,
		struct cgroup_file_info *	info,
		int *	base_level
	)

Walk through the directory tree for the specified controller.

The directory representing base_path is returned in info. Use cgroup_walk_tree_set_flags() to specify, in which order should be next directories returned.

Parameters:

	controller	Name of the controller, for which we want to walk the directory tree.
	base_path	Begin walking from this path. Use "/" to walk through full hierarchy.
	depth	The maximum depth to which the function should walk, 0 implies all the way down.
	handle	Handle to be used during iteration.
	info	Info filled and returned about directory information.
	base_level	Opaque integer which you must pass to subsequent cgroup_walk_tree_next.

Todo:

why base_level is not hidden in **handle?

Returns:

ECGEOF when there is no node.

int cgroup_walk_tree_end

(

void **

handle

)

Release the iterator.

int cgroup_walk_tree_next	(	int	depth,
		void **	handle,
		struct cgroup_file_info *	info,
		int	base_level
	)

Get the next directory in the walk.

Parameters:

	depth	The maximum depth to which the function should walk, 0 implies all the way down.
	handle	Handle to be used during iteration.
	info	Info filled and returned about the next directory.
	base_level	Value of base_level returned by cgroup_walk_tree_begin().

Returns:

ECGEOF when we are done walking through the nodes.

int cgroup_walk_tree_set_flags	(	void **	handle,
		int	flags
	)

Set the flags for walk_tree.

Currently available flags are in cgroup_walk_type enum.

Parameters:

	handle	Handle of the iterator.
	flags