Select Git revision
BOINCClientAdapter.h
Forked from
einsteinathome / graphicsframework
109 commits behind the upstream repository.
-
Oliver Bock authoredOliver Bock authored
BOINCClientAdapter.h 12.67 KiB
/***************************************************************************
* 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_*/