/*
   Copyright Universite de Versailles Saint-Quentin en Yvelines 2009
   AUTHORS: Sebastien Briais, Sid Touati

   This file is part of RS.
   
   RS is free software: you can redistribute it and/or modify it
   under the terms of the GNU Lesser General Public License as
   published by the Free Software Foundation, either version 3 of the
   License, or (at your option) any later version.
   
   RS is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.
   
   You should have received a copy of the GNU Lesser General Public
   License along with RS.  If not, see
   <http://www.gnu.org/licenses/>.
*/
#ifndef __RS_H
#define __RS_H
/** \file rs.h
    \brief Register saturation */ 

#include <GDD/dag.h>
#include <SCEDA/graph.h>

/** Estimate the register saturation for given type.
    Use Greedy-k algorithm.

    @param[in] dag = GDD_DAG
    @param[in] type = considered type
    @param[in] fast = TRUE to use fast version (variant 2 heuristic), FALSE to use precise version (variant 1 heuristic)

    @return an approximation of the register saturation */
int RS_estimate_saturation(GDD_DAG *dag, const char *type, int fast);

/** Estimate the register saturation for given type.
    Use Greedy-k algorithm.

    @param[in] ddg = a DDG (the DAG is built internally)
    @param[in] type = considered type
    @param[in] fast = TRUE to use fast version (variant 2 heuristic), FALSE to use precise version (variant 1 heuristic)

    @return an approximation of the register saturation */
int RS_estimate_saturation_TC(SCEDA_Graph *ddg, const char *type, int fast);

/** Return an approximated set of saturating values for given type.
    Use Greedy-k algorithm.

    @param[in] dag = GDD_DAG
    @param[in] type = considered type
    @param[out] sat_values = list of saturating values

    @return 0 in case of success, a negative value otherwise */
int RS_estimate_saturating_values(GDD_DAG *dag, const char *type, SCEDA_List **sat_values);

/** Return an approximated set of saturating values for given type.
    Use Greedy-k algorithm.

    @param[in] ddg = a DDG (the DAG is built internally)
    @param[in] type = considered type
    @param[out] sat_values = list of saturating values

    @return 0 in case of success, a negative value otherwise */
int RS_estimate_saturating_values_TC(SCEDA_Graph *ddg, const char *type, SCEDA_List **sat_values);

/** Compute the optimal register saturation for considered type.

    @param[in] ddg = a DDG (a DAG is built internally)
    @param[in] type = considered type
    @param[in] timeout = time out in seconds (ignored when < 0)
 
    @param[out] timeout_flag = flag used to indicate whether the
      computation has been interrupted by the timeout
        TRUE when computation has been interrupted: the computed value
        may thus not be optimal
        FALSE otherwise: the computed value is optimal

    @return the register saturation or -1 in case of error (no value
    found during the given amount of time)
*/
int RS_compute_optimal_saturation(SCEDA_Graph *ddg, const char *type, double timeout, int *timeout_flag);

/** \page rs Register saturation estimation and optimal computation

    To get a theoretical introduction to register saturation, see \ref greedy.

    \section rs_api API

    The following functions are available to estimate or compute
    optimal register saturation.

    In the case of the heuristic, there are two variants of the same
    functions: 

    \li one that deals directly with a brute DDG as represented by the GDD library and
    \li another one that deals with a DAG. 

    Internally, the first variant calls the second variant after
    having built a DAG (which costs \f$O(n^3)\f$) and delete the DAG
    after the computation.

    The second variant is visible in order to avoid multiple
    computations of the enriched DAG structure when one has to deal
    with several register types.

    \code
    int RS_estimate_saturation_TC(SCEDA_Graph *ddg, char *type, int fast);
    int RS_estimate_saturation(GDD_DAG *dag, char *type, int fast);
    \endcode

    These two functions estimate register saturation of given type and
    DDG. The estimation method is chosen via the flag.

    They only differ in the way the DDG is given.

    \code
    int RS_estimate_saturating_values_TC(SCEDA_Graph *ddg, char *type, SCEDA_List **sat_values);
    int RS_estimate_saturating_values(GDD_DAG *dag, char *type, SCEDA_List **sat_values);
    \endcode
    
    These two functions estimate a set of saturating values of given
    type and DDG.

    They only differ in the way the DDG is given.

    \code
    int RS_compute_optimal_saturation(SCEDA_Graph *ddg, const char *type, double timeout, int *timeout_flag);
    \endcode

    This function computes optimal register saturation of given type
    and DDG. Since the computation may be very long, it is possible to
    set a timeout (indicated in seconds). 

    \section rs_example Example

    \include "rs/main.c"

*/

#endif