rt_scheduler.h

Go to the documentation of this file.

/*
 * rt_scheduler.h
 *
 * Copyright (c) 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 rt_scheduler.h
 *
 * Common interface for using an OS-level real-time scheduler.  @note This is
 * just an interface, there is no default implementation available, the
 * appropriate one must be selected and linked in.
 *
 * @sa rt_scheduler_unix.c
 * @sa rt_scheduler_rk.c
 */

#ifndef _misc_rt_scheduler_h
#define _misc_rt_scheduler_h

#ifdef __cplusplus
extern "C" {
#endif

#include <sys/types.h>
#include <sys/time.h>

enum {
    RSDB_RESERVATIONS,
};

enum {
    /** The scheduler supports CPU reservations. */
    RSDF_RESERVATIONS = (1L << RSDB_RESERVATIONS),
};

/*
 * Data structure used to communicate information about the properties of the
 * underlying scheduler.
 *
 * rsd_Flags - Field used to store RSDF_RESERVATIONS.
 * rsd_MaxReservable - The maximum fraction of CPU that can be reserve.
 */
typedef struct rts_scheduler_data {
    unsigned long rsd_Flags;
    float rsd_MaxReservable;
} *rts_scheduler_data_t;

/**
 * Get information about the underlying scheduler.  This function is mostly
 * about making it possible to do run-time adaptation to the scheduler's
 * capabilities.
 *
 * @param rsd_out A reference to an #rts_scheduler_data object that should be
 * filled in.
 */
extern int rts_query_scheduler(rts_scheduler_data_t rsd_out);

/**
 * An opaque reference to scheduler specific data.  The schedulable is used to
 * collect multiple processes under a single schedulable entity.  For example,
 * TimeSys Linux schedules a "resource set", which in turn, schedules a process
 * in that set.
 *
 * @see rts_grab_schedulable
 * @see rts_release_schedulable
 */
typedef void *rts_schedulable_t;

/**
 * Grab a reference to a schedulable entity.  The current semantics of this
 * function are as follows:
 *
 * @li If necessary, the function must make some effort to "repair" the system
 * state by destroying schedulables that are in a suspicious state.
 * @li Multiple calls to this function with the same parameters need not return
 * the same pointer, however, their values must be equal.  The user must also
 * release the schedulables in the opposite order in which they were grabbed.
 * @li If the schedulable entity already exists at the OS-level, it should be
 * used instead of creating a new one.
 * @li If no schedulable entity exists that contains the given process or has
 * the given name, one should be created.
 *
 * @param rs_out A pointer that should be filled out with the schedulable
 * value.
 * @param member A process that is already a member of the schedulable, one
 * that should be added to a newly created schedulable, or -1 if the
 * schedulable should be created by name.
 * @param name The name for the schedulable or NULL if one should be made up.
 * @return Zero on success, otherwise, an errno code.
 */
extern int rts_grab_schedulable(rts_schedulable_t *rs_out,
                                pid_t member,
                                const char *name);

/**
 * Release a reference to a schedulable entity.  The current semantics of this
 * function are as follows:
 *
 * @li If the given schedulable created the OS-level entity, this call should
 * destroy it.
 * @li If the given schedulable entity was used to set the schedule, this call
 * should clear the schedule.
 *
 * @param rs The reference from #rts_grab_schedulable to release.
 * @return Zero on success, otherwise an errno value.
 */
extern int rts_release_schedulable(rts_schedulable_t rs);

/**
 * The reservation mode.
 */
typedef enum {
    RTS_RSV_MIN,        /**< Minimum allowed value. */
    RTS_RSV_SOFT,       /**< Soft reservation - use best-effort when needed. */
    RTS_RSV_HARD,       /**< Hard reservation - never use best-effort. */
    RTS_RSV_MAX         /**< Maximum allowed value. */
} rts_reserve_mode_t;

/*
 * A description of the schedulable's CPU schedule.
 *
 * rs_Period - The schedulable's period.
 * rs_ComputeTime - The schedulable's compute time.
 * rs_ReserveMode - The schedulable's reservation mode.
 */
typedef struct rts_schedule {
    struct timespec rs_Period;
    struct timespec rs_ComputeTime;
    rts_reserve_mode_t rs_ReserveMode;
} *rts_schedule_t;

/**
 * Set the real-time schedule for a schedulable.
 *
 * @param rsa The schedulable to schedule.
 * @param rs The new schedule.
 * @return Zero on success, otherwise, an errno code.
 */
extern int rts_set_schedule(rts_schedulable_t rsa, rts_schedule_t rs);

/**
 * Get the real-time schedule for a schedulable.
 *
 * @param rsa The schedulable to schedule.
 * @param rs_out The new schedule.
 * @return Zero on success, otherwise, an errno code.
 */
extern int rts_get_schedule(rts_schedulable_t rsa, rts_schedule_t rs_out);

/**
 * Clear the real-time schedule for a schedulable and return it to a
 * best-effort scheduler.
 *
 * @param rsa The schedulable to clear.
 * @return Zero on success, otherwise, an errno code.
 */
extern int rts_clear_schedule(rts_schedulable_t rsa);

#ifdef __cplusplus
}
#endif

#endif

---