#ifndef _LXC_STATS_H_
# define _LXC_STATS_H_

# include <stdint.h>

/**
 * @mainpage liblxcstats API Reference
 *
 * @section sec_about About
 *
 * The liblxcstats returns resources usage statistics on the LXC Containers
 * found on your system in a convenient data structure. LXC, Linux Containers,
 * are like chroots on steroids.
 *
 * LXC uses the cgroup Linux kernel feature. Unlike other software
 * virtualization technique (such as OpenVZ), LXC works on a vanilla Linux
 * kernel.
 *
 * The code assumes that the cgroup hierarchy has been created by LXC. In the
 * future this library could become a generic cgroup statistics library.
 *
 * This library is used to implement the LXC plugin for Collectd.
 *
 * @section see_also See Also
 *
 *   - <a href="http://lxc.sourceforge.net/">LXC Containers</a>;
 *   - <a href="http://collectd.org/">Collectd</a>.
 */

/**
 * Opaque structure used as a context for all liblxcst functions.
 */
typedef struct _lxcst_controller    lxcst_handle;

/**
 * This structure contains available statistics on a container.
 */
struct              lxcst {
    char            *name;      /*< Name of the container                               */
    char            *cgroup_dir;/*< cgroup directory of the container                   */
    struct  {
        uint32_t    user;       /*< CPU time spent in userland                          */
        uint32_t    system;     /*< CPU time spent in kernelland                        */
        uint32_t    *percpu;    /*< CPU time per CPU (zero-terminated array or NULL)    */
    }               cpuacct;    /*< CPU accounting in USER_HZ                           */
    struct {
        uint64_t    used;       /*< RAM used by applications                            */
        uint64_t    mapped;     /*< RAM used for mapped file (includes tmpfs/shmem)     */
        uint64_t    cached;     /*< RAM cached by the kernel                            */
        uint64_t    swapped;    /*< SWAP used                                           */
    }               memory;     /*< Memory accounting in bytes                          */
};

/**
 * This structure contains globals statistics on LXC.
 *
 * Note: see how lxc-info gets these infos.
 */
struct          lxcst_globals {
    uint16_t    running_containers;
    uint16_t    stopped_containers;
};

/**
 * @brief Initialize the library.
 *
 * @return A pointer to an opaque structure which can be free'd with free
 * or NULL on failure with errno set.
 *
 * @see lxcst_close
 */
lxcst_handle    *lxcst_open(void);

/**
 * @brief Close the library.
 *
 * @param [in] hdl The pointer returned by lxcst_open.
 *
 * @return 0 on success, -1 if an error occured with errno set.
 */
int             lxcst_close(lxcst_handle *hdl);

/**
 * @brief Collect statistics on all containers.
 *
 * Walk the cgroup pseudo filesystem and get statistics for all found
 * containers. Also refresh the global statistics struture.
 *
 * @param [in] hdl The pointer returned by lxcst_handle.
 * @param [in] cb A function pointer to a callback which takes a pointer to an
 * user context and a pointer to lxcst structure.
 * @param [in] ctx A pointer to an user defined variable which will be used as
 * an argument to the callback. If the callback returns non zero
 * lxcst_span_containers stops and return with -1 with errno set to EINTR.
 *
 * @return 0 on success, -1 on error with errno set.
 *
 * @see lxcst_globals_statistics
 * @see struct lxcst
 */
int             lxcst_span_containers(lxcst_handle *hdl, int (*cb)(void *, const struct lxcst *), void *ctx);

/**
 * @brief Get a copy of the global LXC statistics object.
 *
 * @param [out] sb A pointer to a struct lxcst_globals.
 *
 * @see struct lxcst_globals
 * @see lxcst_span_containers
 */
void            lxcst_globals_statistics(struct lxcst_globals *sb);

#endif