childProcess.h

Go to the documentation of this file.

/*
 * childProcess.h
 *
 * Copyright (c) 2003 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 childProcess.h
 *
 * Header file for the child process accounting functions.
 */

#ifndef _child_process_h
#define _child_process_h

#ifdef __cplusplus
extern "C" {
#endif

#include <sys/types.h>

#include <listNode.h>

/*
 * A cpChildProcess is used to track and record the resource usage of a child
 * process.
 *
 * cp_Link - List link.
 * cp_PID - The process ID of the child.
 * cp_ProcFileName - The path to the process stats for this child in /proc.
 * cp_Output - The statistics file for this child.
 * cp_LastUsage - The last recorded usage for this child.  Used to compute
 *   the difference in usage between the current and last sample time.
 */
struct cpChildProcess {
    struct lnMinNode cp_Link;
    pid_t cp_PID;
    const char *cp_ProcFileName;
    FILE *cp_Output;
#if defined(linux) || defined(__FreeBSD__)
    struct timeval cp_LastUsage;
#else
#error "Implement me"
#endif
};

enum {
    CPDB_INITIALIZED,
};

/*
 * Flags for the cpChildProcessData structure.
 *
 * CPDF_INITIALIZED - The global data is initialized.
 */
enum {
    CPDF_INITIALIZED = (1L << CPDB_INITIALIZED),
};

/*
 * Global data for tracking child processes.
 *
 * cpd_Flags - Holds the CPDF_ flags.
 * cpd_Children - The list of child processes.
 */
struct cpChildProcessData {
    unsigned long cpd_Flags;
    struct lnMinList cpd_Children;
};

/**
 * Initialize the internal accounting data structures.
 *
 * @return True on success, false otherwise.
 */
int cpInitChildProcessData(void);

/**
 * Deinitialize the internal accounting data structures.
 */
void cpKillChildProcessData(void);

/**
 * Find the cpChildProcess structure that corresponds to the given ID.
 *
 * @param child_pid The child process to track.
 * @return The cpChildProcess object that corresponds to the given ID or NULL
 * if one has not been created yet.
 */
struct cpChildProcess *cpFindChildProcess(pid_t child_pid);

/**
 * Create a cpChildProcess object for a child that does not have one yet.
 *
 * @callgraph
 *
 * @param child_pid The child process to track.
 * @return The newly created object or NULL if a problem was encountered
 * during creation.
 */
struct cpChildProcess *cpCreateChildProcess(pid_t child_pid);

/**
 * Delete the given cpChildProcess object.
 *
 * @param cp NULL or a previously created cpChildProcess object.
 */
void cpDeleteChildProcess(struct cpChildProcess *cp);

/**
 * Open and initialize the statistics output file for the given cpChildProcess
 * object.  The created file will have the form "<base_name>-<pid>.out".
 *
 * @param cp A valid cpChildProcess object.
 * @param base_name The file name prefix.
 * @param start_time The start time for the parent process.
 * @return True if the file was created successfully, false otherwise.
 */
int cpOpenOutput(struct cpChildProcess *cp,
                 const char *base_name,
                 struct timeval *start_time);

/**
 * Sample the resource usage for a given child process.
 *
 * @param cp A valid cpChildProcess object.
 * @param run_time The amount of time the parent process has been running.
 * @return The CPU usage, in microseconds, for the given child process.
 */
unsigned long long cpSampleUsage(struct cpChildProcess *cp,
                                 struct timeval *run_time);

#ifdef __cplusplus
}
#endif

#endif

---