/*************************************************************************** * Copyright (C) 2008 by Oliver Bock * * oliver.bock[AT]aei.mpg.de * * * * This file is part of Einstein@Home. * * * * Einstein@Home is free software: you can redistribute it and/or modify * * it under the terms of the GNU General Public License as published * * by the Free Software Foundation, version 2 of the License. * * * * Einstein@Home 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 General Public License for more details. * * * * You should have received a copy of the GNU General Public License * * along with Einstein@Home. If not, see <http://www.gnu.org/licenses/>. * * * ***************************************************************************/ #ifndef BOINCCLIENTADAPTER_H_ #define BOINCCLIENTADAPTER_H_ #include <iostream> #include <string> #include <sstream> #include "boinc_api.h" #include "graphics2.h" #include "XMLProcessorInterface.h" using namespace std; /** * \addtogroup framework Framework * @{ */ /** * \brief Adapter class which facilitates communications with the BOINC client * * This adapter class can be used to query the BOINC core client for information * about the user and the running science application instance. * * \author Oliver Bock\n * Max-Planck-Institute for Gravitational Physics\n * Hannover, Germany */ class BOINCClientAdapter { public: /** * \brief Constructor * * It takes as an argument the name of the shared memory area to be used * for inter-process communication. * * \param sharedMemoryAreaIdentifier The identifier of the shared memory area */ BOINCClientAdapter(string sharedMemoryAreaIdentifier); /// Destructor virtual ~BOINCClientAdapter(); /** * \brief Defined quality settings for graphics applications * * \see graphicsQualitySetting * \see graphicsFrameRate */ enum GraphicsQualitySetting { LowGraphicsQualitySetting = 1, MediumGraphicsQualitySetting = 2, HighGraphicsQualitySetting = 4 }; /** * \brief Initializes the BOINC client adapter instance * * This method has to be called first, otherwise no data will be returned when requested! */ void initialize(); /** * \brief Refreshes dynamic data (e.g. search information) * * You want to call this method periodically to refresh any volatile client information. * Please make sure that you call initialize() first! * * \see AbstractGraphicsEngine::refreshBOINCInformation * \see initialize */ void refresh(); /** * \brief Retrieves the BOINC core client version of the currently active client * * \return The BOINC core client version */ string coreVersion() const; /** * \brief Retrieves the \b Einstein\@Home application name of the currently active work unit * * \return The \b Einstein\@Home application name */ string applicationName() const; /** * \brief Retrieves the \b Einstein\@Home application version of the currently active work unit * * \return The \b Einstein\@Home application version */ string applicationVersion() const; /** * \brief Retrieves the BOINC user name currently logged in * * \return The BOINC user name */ string userName() const; /** * \brief Retrieves the BOINC team name of the currently logged in user * * \return The BOINC team name */ string teamName() const; /** * \brief Retrieves the total project credit of the currently logged in user * * \return The total project credit */ double userCredit() const; /** * \brief Retrieves the recent average project credit (RAC) of the currently logged in user * * \return The recent average project credit */ double userRACredit() const; /** * \brief Retrieves the total project credit of this host * * \return The total project credit */ double hostCredit() const; /** * \brief Retrieves the recent average project credit (RAC) of this host * * \return The recent average project credit */ double hostRACredit() const; /** * \brief Retrieves the name of the currently active work unit * * \return The work unit name */ string wuName() const; /** * \brief Retrieves the estimated number of floating-point operations to complete the currently active work unit. * * An estimate of the average number of floating-point operations (FPOPS) required to complete the computation. * This is used to estimate how long the computation will take on a given host. * * \return The estimated number of FPOPS to complete the currently active work unit */ double wuFPOpsEstimated() const; /** * \brief Retrieves the maximum number of floating-point operations allowed for the currently active work unit. * * A bound on the number of floating-point operations (FPOPS) required to complete the computation. * If this bound is exceeded, the application will be aborted. * * \return The maximum number of FPOPS allowed for the currently active work unit */ double wuFPOpsBound() const; /** * \brief Retrieves an estimate of application's largest working set size. * * An estimate of application's largest working set size. * The workunit will only be sent to hosts with at least this much available RAM. * * \return The estimate of application's largest working set size */ double wuMemoryBound() const; /** * \brief Retrieves the maximum disk space allowed to be used by the application. * * A bound on the maximum disk space used by the application, including all input, temporary, and output files. * The workunit will only be sent to hosts with at least this much available disk space. * If this bound is exceeded, the application will be aborted. * * \return The maximum disk space allowed to be used by the application */ double wuDiskBound() const; /** * \brief Retrieves the accumulated time spent on the currently active work unit * * \return The time spent on the work unit */ double wuCPUTimeSpent() const; /** * \brief Retrieves information provided by the running science application * * \return The application specific information string (i.e. XML) found in APP_INIT_DATA * * \see m_UserData */ string applicationInformation() const; /** * \brief Retrieves specific information provided by the currently active project * * All projects using this framework are highly recommended to adhere to the following XML schema * (not yet literally a XML schema, will be provided later) with respect to graphics settings: * \verbatim <project_preferences> <graphics fps="20" quality="low" width="800" height="600"> <engine name="starsphere"> <feature id="globe" enabled="true" /> </engine> <engine name="waverider"> <feature id="sound" enabled="false" /> </engine> </graphics> </project_preferences> \endverbatim * * The \c graphics tag and its four attributes \b must be provided as shown above where * the \c fps attribute contains the frame rate as integer value and \c quality contains * a lowercase string value describing the quality setting to be used (supported values: \c low, * \c medium, \c high). The two remaining attributes \c width and \c height determine the initial * window size when starting in windowed mode. Please note that the children of the \c graphics * tag are recommendations of how graphics application specific settings (e.g. features) should be * stored per implementation. * * \return The project specific information string (i.e. XML) found in \c APP_INIT_DATA * * \see m_UserData * \see GraphicsQualitySetting * \see graphicsFrameRate * \see graphicsQualitySetting */ string projectInformation() const; /** * \brief Retrieves the frame rate at which the project's graphics application should be rendered * * This setting is given by the \c fps attribute of the \c graphics tag that's * part of the \c project_specific XML tag. * * \return The frame rate to be used for rendering * * \see projectInformation * \see m_UserData */ int graphicsFrameRate() const; /** * \brief Retrieves the quality setting at which the project's graphics application should be rendered * * This setting is given by the \c quality attribute of the \c graphics tag that's * part of the \c project_specific XML tag. * * \return The quality setting to be used for rendering * * \see GraphicsQualitySetting * \see projectInformation * \see m_UserData */ GraphicsQualitySetting graphicsQualitySetting() const; /** * \brief Retrieves the initial window width when running in windowed mode * * This setting is given by the \c width attribute of the \c graphics tag that's * part of the \c project_specific XML tag. It's ignored when the application * is started in fullscreen/screensaver mode. * * \return The initial window width to be used * * \see projectInformation * \see m_UserData */ int graphicsWindowWidth() const; /** * \brief Retrieves the initial window height when running in windowed mode * * This setting is given by the \c height attribute of the \c graphics tag that's * part of the \c project_specific XML tag. It's ignored when the application * is started in fullscreen/screensaver mode. * * \return The initial window height to be used * * \see projectInformation * \see m_UserData */ int graphicsWindowHeight() const; private: /** * \brief Fetch the contents of \c init_data.xml * * This method uses the BOINC API in order to fill the \c APP_INIT_DATA structure m_UserData * with initial information about the current work unit computation session (slot). The data * in \c init_data.xml is refreshed only at the beginning of a session, hence this method doesn't * need to be called periodically. */ void readUserInfo(); /** * \brief Fetch the contents of the shared memory area provided by the \b Einstein\@Home application * * The shared memory area contains various informational bits and pieces about the running application * and work unit computation. The contents have to be considered as volatile, hence should be refreshed * periodically. * * \see refresh() */ void readSharedMemoryArea(); /** * \brief Parse the project-specific preferences (XML) * * The project-specific preferences are retrieved by projectInformation(). * This method parses the XML string returned and populates the respective data members. * * \see projectInformation() * \see m_GraphicsFrameRate * \see m_GraphicsQualitySetting * \see m_GraphicsWindowWidth * \see m_GraphicsWindowHeight */ void readProjectPreferences(); /// State flag which indicates whether the adapter instance is ready to be used bool m_Initialized; /// Name tag used to identify the shared memory area provided by the \b Einstein\@Home application string m_SharedMemoryAreaIdentifier; /// Pointer to the shared memory area char *m_SharedMemoryArea; /// The contents of the shared memory area after the last refresh string m_SharedMemoryAreaContents; /// Flag to indicate whether the shared memory area is available or not bool m_SharedMemoryAreaAvailable; /// Frame rate at which the project's graphics application should be rendered int m_GraphicsFrameRate; /// Quality setting at which the project's graphics application should be rendered GraphicsQualitySetting m_GraphicsQualitySetting; /// Initial window width when running in windowed mode int m_GraphicsWindowWidth; /// Initial window height when running in windowed mode int m_GraphicsWindowHeight; /** * \brief Information structure returned by the BOINC client API. * * It contains information about the currently active project, science application, * user account, work unit and computation session. */ APP_INIT_DATA m_UserData; /// Pointer to the XML processor XMLProcessorInterface* m_xmlIFace; }; /** * @} */ #endif /*BOINCCLIENTADAPTER_H_*/