root/vtcross/trunk/src/include/vtcross/cognitive_engine.h @ 518

/*
 Copyright 2009 Virginia Polytechnic Institute and State University  

 Licensed under the Apache License, Version 2.0 (the "License"); 
 you may not use this file except in compliance with the License. 
 You may obtain a copy of the License at 
 
 http://www.apache.org/licenses/LICENSE-2.0 

 Unless required by applicable law or agreed to in writing, software 
 distributed under the License is distributed on an "AS IS" BASIS, 
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
 See the License for the specific language governing permissions and 
 limitations under the License. 
*/

/*! This header exports the declaration for the Cognitive Engine component type.
 */

#ifndef COGNITIVE_ENGINE_H
#define COGNITIVE_ENGINE_H


#include "components.h"


/*! \brief Cognitive Engine class declaration.
 *
 * All public functions are inherited from parent classes.  Please see parent
 * class definitions for function documentation.
 */
class CognitiveEngine : public Engine
{
    public:
        /*! Default constructor. */
        CognitiveEngine();

        /*! Default destructor. */
        ~CognitiveEngine();

        /*! \brief Preferred constructor.
         *
         * Overloaded constructor that creates a cognitive engine object and
         * connects it to either the shell or an SML, depening on the SML bool.
         */
        CognitiveEngine(const char* serverName, const char* serverPort, \
                const bool SML);
        
        void SendComponentType();
        void ConnectToRemoteComponent(const char* serverName, \
                const char* serverPort, const bool SML);
        void WaitForSignal();
        void Shutdown();
        void Reset();
        void RegisterComponent();
        void DeregisterComponent();

        void RegisterServices();
        void DeregisterServices();

    private:
        /*! \brief Receive radio XML configuration.
         * 
         * Receive the transmitted radio configuration from the radio itself
         * (the CE will not always be local to the radio). This gets passed
         * through either the Shell or the SML. */
        void ReceiveRadioConfiguration();

        /*! \brief Receive an 'experience' report from the radio.
         *
         * An experience report can be used to build the transmission history
         * for a CE just starting up so that it has a moving start regarding
         * parameter optimization. */
        void ReceiveExperience();

        /*! \brief Request that the CE optimize a set of parameters. 
         *
         * Find the most optimal set of transmission parameters given certain
         * observables and possibly a service if the SML component is present
         * and active. */
        Parameter *GetSolution(Observable *observables, \
                Parameter *currentParameters);
        Parameter *GetSolution(Observable *observables, \
                Parameter *currentParameters, std::string service);

        /*! \brief Receive feedback from the radio 
         *
         * Receive a feedback from the radio regarding the performance of a
         * certain set of parameters, possibly associated with a service.
         *
         * Feedback is a single set of performance statistics that is achieved
         * corresponding to a specific set of transmission parameters.  Feedback
         * helps a Cognitive Engine make better future decisions based upon 
         * more accurate performance statistics. 
         */
        void ReceiveFeedback(Observable *observables,Parameter *parameters);
        void ReceiveFeedback(Observable *observables, Parameter *parameters, \
                std::string service);


        /*! \brief Initialize the CE and prepare it for operation. 
         *
         * BuildCognitiveEngine performs the CE implementation specific work
         * that defines the internals of a CE.  For example, a CBR CE engine
         * would build the case-base reasoner or create the database, a neural
         * network based CE may perform the initial training, a GA based CE
         * may build the chromosome structure.
         */
        void BuildCognitiveEngine();

        /*! \brief Keept track of what this CE is connected to. 
         *
         * The SML_present bool reflects whether or not the remote component
         * this object is connected to is an SML.  If it isn't, then it must be
         * a shell.  The socketFD stores the socket file descriptor for this
         * connection.
         */
        bool SML_present;
        int32_t commandSocketFD;
        
        // TODO Need a description for these fields.  Are these radio utilites,
        // parameters, and observables global to the whole system?
        Utility *uList;
        Parameter *pList;
        Observable *oList;
        struct Radio_Info *radioInfo;
};

#endif