/*
 * sga-manager.idl
 *
 * $Author: oikawa $
 * $Revision: 117497 $ - $Date: 2011-04-25 16:26:07 -0300 (Mon, 25 Apr 2011) $
 */

#ifndef _SGA_MANAGER_IDL
#define _SGA_MANAGER_IDL

#include "sga-daemon.idl" 

/** 
 * Interfaces entre SGA e SSI (SGA Manager) para gerência da execução remota
 * de algoritmos.
 */
module sgaidl {

   interface SGAServer;
   interface SGACommand;

   /**
    * Capacidades de cada SGA medidas através de benchmarks 
    */
   enum CType {
     CPU,
     DISK_READ,
     DISK_WRITE,
     NET
   };

   /**
    * Estrutura que armazena o valor de cada benchmark por sga
    */
   struct Capacity {
     CType type;
     long value;
   };

   /**
    * Carga na máquina hospedeira do SGA.
    * Essa informação corresponde ao percentual de ocupação do(s) 
    * processador(es) do nó. Deve-se observar que este 
    * percentual pode ser maior que 100% (valor superior a 1.0) caso o número
    * de processos ativos exceda o número de processadores disponíveis.
    */
   struct HostLoadAvgPerc {
     double loadAvg1min;  /**< carga no último minuto */
     double loadAvg5min;  /**< carga nos últimos 5 minutos */
     double loadAvg15min; /**< carga nos últimos 15 minutos */
   };

   /**
    * Tipos de ordenação de bytes de processador.
    */
   enum ByteOrder {
     LITTLE_ENDIAN,
     BIG_ENDIAN
   };

   struct StaticNodeInfo {
     string name;                   /**< Nome do nó */
     string platform_id;            /**< Identificador de plataforma do nó */
     long num_processors;           /**< Num. de processadores do nó */
     long memory_ram_info_mb;       /**< Tamanho da memória RAM do nó */
     long memory_swap_info_mb;      /**< Tamanho da memória de swap do nó */
     long clock_speed_mhz;          /**< Velocidade do processador do nó. */
     string file_separator;         /**< Separador de arquivos. */
     string project_root_directory; /**< Diretório raiz para localização do repositório de projetos. */
     string algorithm_root_directory; /**< Diretório raiz para localização do repositório de algoritmos. */
     string sandbox_root_directory; /**< Diretório raiz para localização das sandboxes de execução dos comandos. */
     ByteOrder byte_order;          /**< Ordernação de bytes no processador do nó. */
     sequence<string> requirements; /** Requisitos que um sga possui */
     sequence<Capacity> capacities; /**< Resultados dos benchmarks */
   };

   struct DynamicNodeInfo {
     string name;                       /**< Nome do nó */
     HostLoadAvgPerc load_avg_perc;     /**< Carga de CPU */
     double memory_ram_free_perc;       /**< Memória RAM livre */
     double memory_swap_free_perc;      /**< Memória swap livre */
     long number_of_jobs;               /**< Número de jobs em execução no nó */
     sequence<Capacity> capacities;     /**< Resultados dos benchmarks */
   };

   typedef sequence<StaticNodeInfo> NodesStaticInfo;
   typedef sequence<DynamicNodeInfo> NodesDynamicInfo;

   struct SGADynamicInfo {
     boolean hasDiskAccess;      /* indica se o SGA tem acesso ao disco. */
     string jobsInfo;            /* informações sobre os jobs em execução no SGA */
     NodesDynamicInfo nodesInfo; /* informações dinâmicas de cada nó. */
   };

   /**
    * Informações sobre o fim da execução de um comando.
    * Essas informações correspondem, basicamente, às estatísticas fornecidas 
    * pelo comando 'time'.
    */
   struct CompletedCommandInfo {
     long elapsedTimeSec;
     long userTimeSec;
     long cpuTimeSec;
   };

   /**
    * Informações sobre um comando recuperado.
    * cmdid  identificação do comando recuperado
    * cmdRef referência para o gerenciador de comando
    */
   struct RetrievedInfo {
     string     cmdId;
     SGACommand cmdRef;
   };

   /**
    * Informações de todos os comandos que foram recuperados.
    */
   typedef sequence<RetrievedInfo> RetrievedCmds;

   /**
    * Interface implementada pelo SGA Manager (SSI)
    */
   interface SGAManager {
      /**
       * SGA avisa ao manager que está ativo.
       * @param sga referência para o SGA
       * @param hostname nome da máquina hospedeira do SGA
       * @param nodesstaticinfo informações estáticas do SGA.
       * @param updateInterval informa de quanto em quanto tempo o SGA
       *        deve dizer que está vivo.
       * @return true se o SGA foi registrado com sucesso junto ao SSI
       */
      boolean registerSGA( in SGAServer sga, in string hostname,
        in NodesStaticInfo sinfo, out long updateInterval );

      /**
       * SGA avisa ao manager que sairá do ar.
       * @param sga referência para o SGA
       * @param hostname nome da máquina hospedeira do SGA
       */
      void unregisterSGA( in SGAServer sga, in string hostname );

      /**
       * SGA envia seus os dados dinâmicos para o Manager.
       * @param sga referência para o SGA
       * @param hostname nome da máquina hospedeira do SGA
       * @param dinfo informações dinâmicas do SGA.
       * @return true se atualizou as informações
       */
      boolean updateSGAInfo( in SGAServer sga, in string hostname,
        in SGADynamicInfo dinfo );

      /**
       * SGA avisa ao manager que está apto a receber novos comandos.
       * @param sga referência para o SGA
       * @param hostname nome da máquina hospedeira do SGA
       */
      void setSGAEnabled(in SGAServer sga, in string hostname );

      /**
       * SGA avisa ao manager que não pode receber novos comandos.
       * Essa notificação é enviada quando, através de algum procedimento
       * local à máquina hospedeira, o SGA é solicitado a suspender,
       * temporariamente, a execução de novos comandos (por exemplo,
       * em caso de necessidade de reserva dos recursos da máquina hospedeira
       * para a execução de uma tarefa prioritária). No entanto, o SGA
       * e os gerenciadores de comandos em execução continuarão ativos,
       * e atendendo a requisições de monitoração.
       * @param sga referência para o SGA
       * @param hostname nome da máquina hospedeira do SGA
       */
      void setSGADisabled(in SGAServer sga, in string hostname);

      /**
       * SGA avisa ao manager que um comando terminou.
       * @param cmd referência para o gerenciador de comando
       * @param info informações sobre o término de execução do comando
       * @return true se o Manager aceitou a notificação
       *         false se o Manager desconhece o SGA 
       *          (pode acontecer se o Manager esteve fora do ar, 
       *           o que exige um novo registro do SGA)
       */
      boolean commandCompleted( in string hostname,
           in SGACommand cmd, in string cmdid,
           in CompletedCommandInfo info, in string cmdstring );

      /**
       * SGA avisa ao manager que um comando foi perdido.
       * @return true se o Manager aceitou a notificação
       *         false se o Manager desconhece o SGA 
       *          (pode acontecer se o Manager esteve fora do ar, 
       *           o que exige um novo registro do SGA)
       */
      boolean commandLost( in string hostname,
           in string cmdid, in string cmdstring );

      /**
       * SGA avisa ao manager que um comando foi recuperado.
       * @param sganame nome da máquina hospedeira do SGA
       * @param cmds comandos recuperados pelo SGA.
       * @return true se os comandos foram registrados com sucesso junto ao SSI
       */
      boolean commandRetrieved( in string sganame, in RetrievedCmds cmds);

      /**
       * SGA indica que está acessível.
       * @return true se o SGA estava acessível e seu registro está válido.
       */
      boolean isRegistered(in SGAServer sga, in string hostname);
   };

};

#endif
