3. Iterators

Data Structures
struct	cgroup_file_info
struct	cgroup_stat
struct	cgroup_mount_point
struct	controller_data

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 }
enum	cgroup_file_type { CGROUP_FILE_TYPE_FILE , CGROUP_FILE_TYPE_DIR , CGROUP_FILE_TYPE_OTHER }
int	cgroup_walk_tree_begin (const char *controller, const char *base_path, int depth, void **handle, struct cgroup_file_info *info, int *base_level)
int	cgroup_walk_tree_next (int depth, void **handle, struct cgroup_file_info *info, int base_level)
int	cgroup_walk_tree_end (void **handle)
int	cgroup_walk_tree_set_flags (void **handle, int flags)
int	cgroup_read_value_begin (const char *const controller, const char *path, const char *const name, void **handle, char *buffer, int max)
int	cgroup_read_value_next (void **handle, char *buffer, int max)
int	cgroup_read_value_end (void **handle)

Read group stats
libcgroup's cgroup_get_value_string() reads only relatively short parameters 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)
int	cgroup_read_stats_next (void **handle, struct cgroup_stat *stat)
int	cgroup_read_stats_end (void **handle)
#define	CG_VALUE_MAX   100

List all tasks in a group
Use following functions to read tasks file of a group.
int	cgroup_get_task_begin (const char *cgrp, const char *controller, void **handle, pid_t *pid)
int	cgroup_get_task_next (void **handle, pid_t *pid)
int	cgroup_get_task_end (void **handle)

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)
int	cgroup_get_controller_next (void **handle, struct cgroup_mount_point *info)
int	cgroup_get_controller_end (void **handle)

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)
int	cgroup_get_all_controller_next (void **handle, struct controller_data *info)
int	cgroup_get_all_controller_end (void **handle)

List all mount points of a controller.
Use following functions to list all mount points of a hierarchy with given controller.
int	cgroup_get_subsys_mount_point_begin (const char *controller, void **handle, char *path)
int	cgroup_get_subsys_mount_point_next (void **handle, char *path)
int	cgroup_get_subsys_mount_point_end (void **handle)

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);

Macro Definition Documentation

CG_VALUE_MAX

#define CG_VALUE_MAX   100

Maximum length of a value in stats file.

Enumeration Type Documentation

cgroup_file_type

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?

cgroup_walk_type

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

cgroup_get_all_controller_begin()

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

Read the first of controllers from /proc/cgroups.

Parameters

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

cgroup_get_all_controller_end()

int cgroup_get_all_controller_end

(

void **

handle

)

Release the iterator

cgroup_get_all_controller_next()

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

Read next controllers from /proc/cgroups.

Parameters

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

cgroup_get_controller_begin()

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	The handle to be used for iteration.
info	The variable where the path to the controller is stored.

Returns

ECGEOF when no controllers are mounted.

cgroup_get_controller_end()

int cgroup_get_controller_end

(

void **

handle

)

Release the iterator.

cgroup_get_controller_next()

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	The 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.

cgroup_get_subsys_mount_point_begin()

int cgroup_get_subsys_mount_point_begin	(	const char *	controller,
		void **	handle,
		char *	path )

Read the first mount point of the hierarchy with given controller. The first is the same as the mount point returned by cgroup_get_subsys_mount_point().

Parameters

handle	The handle to be used for iteration.
controller	The controller name.
path	Buffer to fill the path into. The buffer must be at least FILENAME_MAX characters long.

cgroup_get_subsys_mount_point_end()

int cgroup_get_subsys_mount_point_end

(

void **

handle

)

Release the iterator.

cgroup_get_subsys_mount_point_next()

int cgroup_get_subsys_mount_point_next	(	void **	handle,
		char *	path )

Read next mount point of the hierarchy with given controller.

Parameters

handle	The handle to be used for iteration.
path	Buffer to fill the path into. The buffer must be at least FILENAME_MAX characters long.

cgroup_get_task_begin()

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

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

Parameters

cgrp	Name of the cgroup.
controller	Name of the cgroup subsystem.
handle	The 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.

cgroup_get_task_end()

int cgroup_get_task_end

(

void **

handle

)

Release the iterator.

cgroup_get_task_next()

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.

cgroup_read_stats_begin()

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	The path to control group, relative to hierarchy root.
handle	The handle to be used during iteration.
stat	Returned first item in the stats file.

Returns

ECGEOF when the stats file is empty.

cgroup_read_stats_end()

int cgroup_read_stats_end

(

void **

handle

)

Release the iterator.

cgroup_read_stats_next()

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

Read the next stat value.

Parameters

handle	The 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.

cgroup_read_value_begin()

int cgroup_read_value_begin	(	const char *const	controller,
		const char *	path,
		const char *const	name,
		void **	handle,
		char *	buffer,
		int	max )

Read the value of the given variable for the specified controller and control group. The value is read up to newline character or at most max-1 characters, whichever comes first (i.e. similar to fgets()).

Parameters

controller	Name of the controller for which stats are requested.
path	The path to control group, relative to hierarchy root.
name	is variable name.
handle	The handle to be used during iteration.
buffer	The buffer to read the value into. The buffer is always zero-terminated.
max	Maximal length of the buffer

Returns

ECGEOF when the stats file is empty.

cgroup_read_value_end()

int cgroup_read_value_end

(

void **

handle

)

Release the iterator.

cgroup_read_value_next()

int cgroup_read_value_next	(	void **	handle,
		char *	buffer,
		int	max )

Read the next string from the given variable handle which is generated by cgroup_read_stats_begin() function. the value is read up to newline character or at most max-1 characters, whichever comes first (i.e. similar to fgets()) per cgroup_read_stats_next() call

Parameters

handle	The handle to be used during iteration.
data	returned the string.
buffer	The buffer to read the value into. The buffer is always zero-terminated.
max	Maximal length of the buffer

Returns

ECGEOF when the iterator finishes getting the list of stats.

cgroup_walk_tree_begin()

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	The handle to be used during iteration.
info	The 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.

cgroup_walk_tree_end()

int cgroup_walk_tree_end

(

void **

handle

)

Release the iterator.

cgroup_walk_tree_next()

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	The handle to be used during iteration.
info	The 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.

cgroup_walk_tree_set_flags()

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	The handle of the iterator.
flags