Document the tasks.h

Signed-off-by: Jan Safranek <jsafrane@redhat.com>

1 files changed, 122 insertions, 59 deletions

diff --git a/include/libcgroup/tasks.h b/include/libcgroup/tasks.h
index 913251c..aecfb43 100644
--- a/include/libcgroup/tasks.h
+++ b/include/libcgroup/tasks.h
@@ -12,19 +12,110 @@
 
 __BEGIN_DECLS
 
-/* Flags for cgroup_change_cgroup_uid_gid() */
+/** Flags for cgroup_change_cgroup_uid_gid(). */
 enum cgflags {
+	/** Use cached rules, do not read rules from disk. */
 	CGFLAG_USECACHE = 0x01,
 };
 
+/** Flags for cgroup_register_unchanged_process(). */
 enum cgroup_daemon_type {
+	/**
+	 * The daemon must not touch the given task, i.e. it never moves it
+	 * to any controlgroup.
+	 */
 	CGROUP_DAEMON_UNCHANGE_CHILDREN = 0x1,
 };
 
+/**
+ * @defgroup group_tasks 4. Manipulation with tasks
+ * @{
+ *
+ * @name Simple task assignment
+ * @{
+ * Applications can use following functions to simply put a task into given
+ * control group and find a groups where given tasks is.
+ */
+
+/**
+ * Move current task (=thread) to given control group.
+ * @param cgroup Destination control group.
+ */
 int cgroup_attach_task(struct cgroup *cgroup);
+
+/**
+ * Move given task (=thread) to to given control group.
+ * @param cgroup Destination control group.
+ * @param tid The task to move.
+ */
 int cgroup_attach_task_pid(struct cgroup *cgroup, pid_t tid);
 
 /**
+ * Changes the cgroup of a task based on the path provided.  In this case,
+ * the user must already know into which cgroup the task should be placed and
+ * no rules will be parsed.
+ *
+ * @param path Name of the destination group.
+ * @param pid The task to move.
+ * @param controllers List of controllers.
+ *
+ * @todo should this function be really public?
+ */
+int cgroup_change_cgroup_path(const char *path, pid_t pid,
+		const char * const controllers[]);
+
+/**
+ * Get the current control group path where the given task is.
+ * @param pid The task to find.
+ * @param controller The controller (hierarchy), where to find the task.
+ * @param current_path The path to control group, where the task has been found.
+ * 	The patch is relative to the root of the hierarchy. The caller must
+ * 	free this memory.
+ */
+int cgroup_get_current_controller_path(pid_t pid, const char *controller,
+					char **current_path);
+
+/**
+ * @}
+ *
+ * @name Rules
+ * @{
+ * @c libcgroup can move tasks to control groups using simple rules, loaded
+ * from configuration file. See cgrules.conf man page to see format of the file.
+ * Following functions can be used to load these rules from a file.
+ */
+
+/**
+ * Initializes the rules cache and load it from /etc/cgrules.conf.
+ * @todo add parameter with the filename?
+ */
+int cgroup_init_rules_cache(void);
+
+/**
+ * Reloads the rules list from /etc/cgrules.conf. This function
+ * is probably NOT thread safe (calls cgroup_parse_rules_config()).
+ */
+int cgroup_reload_cached_rules(void);
+
+/**
+ * Print the cached rules table.  This function should be called only after
+ * first calling cgroup_parse_config(), but it will work with an empty rule
+ * list.
+ * @param fp Destination file, where the rules will be printed.
+ */
+void cgroup_print_rules_config(FILE *fp);
+
+/**
+ * @}
+ * @name Rule based task assignment
+ * @{
+ * @c libcgroup can move tasks to control groups using simple rules, loaded
+ * from configuration file. See cgrules.conf man page to see format of the file.
+ * Applications can move tasks to control groups based on these rules using
+ * following functions.
+ */
+
+/**
  * Changes the cgroup of a program based on the rules in the config file.
  * If a rule exists for the given UID, GID or PROCESS NAME, then the given
  * PID is placed into the correct group.  By default, this function parses
@@ -34,13 +125,12 @@ int cgroup_attach_task_pid(struct cgroup *cgroup, pid_t tid);
  * 	CGFLAG_USECACHE: Use cached rules instead of parsing the config file
  *
  * This function may NOT be thread safe.
- * 	@param uid The UID to match
- * 	@param gid The GID to match
- * 	@param procname The PROCESS NAME to match
- * 	@param pid The PID of the process to move
- * 	@param flags Bit flags to change the behavior, as defined above
- * 	@return 0 on success, > 0 on error
- * TODO: Determine thread-safeness and fix of not safe.
+ * @param uid The UID to match.
+ * @param gid The GID to match.
+ * @param procname The PROCESS NAME to match.
+ * @param pid The PID of the process to move.
+ * @param flags Bit flags to change the behavior, as defined in enum #cgflags.
+ * @todo Determine thread-safeness and fix of not safe.
  */
 int cgroup_change_cgroup_flags(uid_t uid, gid_t gid,
 		const char *procname, pid_t pid, int flags);
@@ -51,16 +141,12 @@ int cgroup_change_cgroup_flags(uid_t uid, gid_t gid,
  * correct group.  By default, this function parses the configuration file each
  * time it is called.
  *
- * The flags can alter the behavior of this function:
- *      CGFLAG_USECACHE: Use cached rules instead of parsing the config file
- *
  * This function may NOT be thread safe.
- * 	@param uid The UID to match
- * 	@param gid The GID to match
- * 	@param pid The PID of the process to move
- * 	@param flags Bit flags to change the behavior, as defined above
- * 	@return 0 on success, > 0 on error
- * TODO: Determine thread-safeness and fix if not safe.
+ * @param uid The UID to match.
+ * @param gid The GID to match.
+ * @param pid The PID of the process to move.
+ * @param flags Bit flags to change the behavior, as defined in enum #cgflags.
+ * @todo Determine thread-safeness and fix if not safe.
  */
 int cgroup_change_cgroup_uid_gid_flags(uid_t uid, gid_t gid,
 				pid_t pid, int flags);
@@ -70,59 +156,36 @@ int cgroup_change_cgroup_uid_gid_flags(uid_t uid, gid_t gid,
  * function is deprecated, and cgroup_change_cgroup_uid_gid_flags() should be
  * used instead.  In fact, this function simply calls the newer one with flags
  * set to 0 (none).
- * 	@param uid The UID to match
- * 	@param gid The GID to match
- * 	@param pid The PID of the process to move
- * 	@return 0 on success, > 0 on error
+ * @param uid The UID to match.
+ * @param gid The GID to match.
+ * @param pid The PID of the process to move.
  */
 int cgroup_change_cgroup_uid_gid(uid_t uid, gid_t gid, pid_t pid);
 
 /**
- * Changes the cgroup of a program based on the path provided.  In this case,
- * the user must already know into which cgroup the task should be placed and
- * no rules will be parsed.
- *
- *  returns 0 on success.
- */
-int cgroup_change_cgroup_path(const char *path, pid_t pid, const char * const controllers[]);
-
-/**
- * Print the cached rules table.  This function should be called only after
- * first calling cgroup_parse_config(), but it will work with an empty rule
- * list.
- * 	@param fp The file stream to print to
- */
-void cgroup_print_rules_config(FILE *fp);
-
-/**
- * Reloads the rules list, using the given configuration file.  This function
- * is probably NOT thread safe (calls cgroup_parse_rules_config()).
- * 	@return 0 on success, > 0 on failure
- */
-int cgroup_reload_cached_rules(void);
-
-/**
- * Initializes the rules cache.
- * 	@return 0 on success, > 0 on failure
+ * @}
+ * @name Communication with cgrulesengd daemon
+ * @{
+ * Users can use cgrulesengd daemon to move tasks to groups based on the rules
+ * automatically when they change their UID, GID or executable name.
+ * The daemon allows tasks to be 'sticky', i.e. all rules are ignored for these
+ * tasks and the daemon never moves them.
  */
-int cgroup_init_rules_cache(void);
 
 /**
- * Get the current cgroup path where the task specified by pid_t pid
- * has been classified
- */
-int cgroup_get_current_controller_path(pid_t pid, const char *controller,
-					char **current_path);
-
-/**
- * Register the unchanged process to a cgrulesengd daemon.
+ * Register the unchanged process to a cgrulesengd daemon. This process
+ * is never moved to another control group by the daemon.
  * If the daemon does not work, this function returns 0 as success.
- * @param pid: The process id
- * @param flags Bit flags to change the behavior, as defined above
- * @return 0 on success, > 0 on error.
+ * @param pid The task id.
+ * @param flags Bit flags to change the behavior, as defined in
+ * 	#cgroup_daemon_type
  */
 int cgroup_register_unchanged_process(pid_t pid, int flags);
 
+/**
+ * @}
+ * @}
+ */
 __END_DECLS
 
 #endif /* _LIBCGROUP_TASKS_H */