rk_util.h

Go to the documentation of this file.

/*
 * rk_util.h
 *
 * Copyright (c) 2003, 2004 The University of Utah and the Flux Group.
 * All rights reserved.
 *
 * This file is licensed under the terms of the GNU Public License.  
 * See the file "license.terms" for restrictions on redistribution 
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 */

/**
 * @file rk_util.h
 *
 * Header file for utility functions related to the TimeSys resource kernel.
 */

#ifndef _rk_util_h
#define _rk_util_h

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Array element used to cache file descriptors for process' "stat" files.
 *
 * pid - The process ID or zero if this element is not allocated.
 * fd - The cached file descriptor for the process' "stat" file in "/proc".
 * cpu_usage - The total CPU usage for this process.
 */
typedef struct rk_resource_set_proc {
    pid_t pid;
    int fd;
    unsigned long long cpu_usage;
} *rk_resource_set_proc_t;

/*
 * Array structure used to cache per-process data for processes in a resource
 * set.
 *
 * data - The array elements, sorted by pid in smallest to largest order.
 * Allocated elements are packed at the front of the array.
 * used - The number of elements in the array that are in use.
 * length - The number of elements in the array.
 */
typedef struct rk_resource_set_proc_cache {
    rk_resource_set_proc_t data;
    size_t used;
    size_t length;
} *rk_resource_set_proc_cache_t;

/*
 * A structure used to hold the results of a rk_resource_set_get_usage call.
 *
 * proc_count - The number of processes in the resource set at the time of
 * sampling.
 * inactive_cpu_usage - The total CPU usage, in microseconds, for all of the
 * processes that were in the resource set but have since died.  Note:  This
 * value will only be set when a process cache is passed to
 * rk_resource_set_get_usage.
 * active_cpu_usage - The total CPU usage, in microseconds, for all of the
 * living processes in the resource set.
 */
typedef struct rk_resource_set_usage {
    unsigned int proc_count;
    unsigned long long inactive_cpu_usage;
    unsigned long long active_cpu_usage;
} *rk_resource_set_usage_t;

/**
 * Search for a resource set by name and return the first one encountered.
 *
 * @param name The resource set name to search for.
 * @return A valid resource set pointer if the name was found, otherwise,
 * NULL_RESOURCE_SET.
 */
rk_resource_set_t rk_resource_set_get_by_name(const char *name);

/**
 * Compute the total resource usage for all the processes in a resource set.
 * Currently, this is implemented by stepping through all of the processes
 * attached to the resource set and pulling the usage information from
 * "/proc/<pid>/stat".  Unfortunately, the standard kernel does not provide
 * high-resolution data in the "stat" file, so the file in the "patch"
 * directory must be applied to the kernel before this function can be used.
 *
 * @sa rk_util/patch/tslinux-3.1-procstat.patch
 *
 * @param rs The resource set to compute the resource usage for.
 * @param rsu_inout An allocated rk_resource_set_stat_t object where the
 * results should be placed.
 * @param pc_inout The process cache object where data can be stored and reused
 * in future calls to this function.
 * @return Zero on success, otherwise, an errno value.
 */
int rk_resource_set_get_usage(rk_resource_set_t rs,
                              rk_resource_set_usage_t rsu_inout,
                              rk_resource_set_proc_cache_t pc_inout);

/**
 * Release any resources stored in the given process cache.
 *
 * @param pc The process cache whose contents should be released.
 */
void rk_resource_set_proc_cache_release(rk_resource_set_proc_cache_t pc);

#ifdef __cplusplus
}
#endif
    
#endif

---