From 0c59438cf1aee0b2dbf5f63cb4e05e33be2e42fc Mon Sep 17 00:00:00 2001 From: Mark Watkins Date: Sun, 18 Dec 2011 23:20:01 +1000 Subject: [PATCH] More doxygen header documentation --- SleepLib/day.h | 75 +++++++++++++++++++++++++++++++++++-- SleepLib/machine.h | 60 ++++++++++++++++++++++++++++++ SleepLib/session.cpp | 6 +-- SleepLib/session.h | 88 +++++++++++++++++++++++++++++++++++++++++++- common_gui.h | 3 ++ 5 files changed, 224 insertions(+), 8 deletions(-) diff --git a/SleepLib/day.h b/SleepLib/day.h index 6e0e5fdb..c79c9475 100644 --- a/SleepLib/day.h +++ b/SleepLib/day.h @@ -18,65 +18,134 @@ class OneTypePerDay class Machine; class Session; + +/*! \class Day + \brief Contains a list of all Sessions for single date, for a single machine + */ class Day { public: Day(Machine *m); ~Day(); + + //! \brief Add Session to this Day object (called during Load) void AddSession(Session *s); + //! \brief Returns this machines type MachineType machine_type(); + //! \brief Returns the count of all this days sessions' events for this day int count(ChannelID code); + + //! \brief Returns the Minimum of all this sessions' events for this day EventDataType Min(ChannelID code); + + //! \brief Returns the Maximum of all sessions' events for this day EventDataType Max(ChannelID code); + + //! \brief Returns the Count-per-hour of all sessions' events for this day EventDataType cph(ChannelID code); + + //! \brief Returns the Sum-per-hour of all this sessions' events for this day EventDataType sph(ChannelID code); + + //! \brief Returns (and caches) the 90th Percentile of all this sessions' events for this day EventDataType p90(ChannelID code); + + //! \brief Returns the Average of all this sessions' events for this day EventDataType avg(ChannelID code); + + //! \brief Returns the Sum of all this sessions' events for this day EventDataType sum(ChannelID code); + + //! \brief Returns the Time-Weighted Average of all this sessions' events for this day EventDataType wavg(ChannelID code); + + //! \brief Returns a requested Percentile of all this sessions' events for this day EventDataType percentile(ChannelID code,EventDataType percentile); + //! \brief Returns if the cache contains SummaryType information about the requested code bool hasData(ChannelID code, SummaryType type); - QHash m_p90; // 90% cache + //! \brief Cache for holding slow calculated 90th Percentile for this day + QHash m_p90; //EventDataType percentile(ChannelID mc,double percent); - // Note, the following convert to doubles without considering the consequences fully. + // Note, the following convert to doubles without considering the consequences fully.? + + //! \brief Returns the Average of all Sessions setting 'code' for this day EventDataType settings_avg(ChannelID code); + + //! \brief Returns the Time-Weighted Average of all Sessions setting 'code' for this day EventDataType settings_wavg(ChannelID code); + + //! \brief Returns the Sum of all Sessions setting 'code' for this day EventDataType settings_sum(ChannelID code); + + //! \brief Returns the Minimum of all Sessions setting 'code' for this day EventDataType settings_min(ChannelID code); + + //! \brief Returns the Maximum of all Sessions setting 'code' for this day EventDataType settings_max(ChannelID code); + //! \brief Returns the first session time of this day qint64 first() { return d_first; } + + //! \brief Returns the last session time of this day qint64 last() { return d_last; } + + //! \brief Sets the first session time of this day void setFirst(qint64 val) { d_first=val; } + + //! \brief Sets the last session time of this day void setLast(qint64 val) { d_last=val; } + + //! \brief Returns the last session time of this day for the supplied Channel code qint64 first(ChannelID code); + + //! \brief Returns the last session time of this day for the supplied Channel code qint64 last(ChannelID code); + //! \brief Returns the total time in milliseconds for this day + qint64 total_time(); - qint64 total_time(); // in milliseconds + //! \brief Return the total time in decimal hours for this day EventDataType hours() { return double(total_time())/3600000.0; } + //! \brief Return the session indexed by i Session *operator [](int i) { return sessions[i]; } + //! \brief Return the first session as a QVector::iterator QVector::iterator begin() { return sessions.begin(); } + //! \brief Return the end session record as a QVector::iterator QVector::iterator end() { return sessions.end(); } + + //! \brief Finds and returns the index of a session, otherwise -1 if it's not there int find(Session * sess) { return sessions.indexOf(sess); } + + //! \brief Returns the number of Sessions in this day record int size() { return sessions.size(); } + Machine *machine; + //! \brief Loads all Events files for this Days Sessions void OpenEvents(); + + //! \brief Returns this days sessions list QVector & getSessions() { return sessions; } + + //! \brief Returns true if this Day contains loaded Event Data for this channel. bool channelExists(ChannelID id); + + //! \brief Returns true if this Day contains loaded Event Data or a cached count for this channel bool channelHasData(ChannelID id); + + //! \brief Returns true if this day contains the supplied settings Channel id bool settingExists(ChannelID id); protected: + //! \brief A Vector containing all sessions for this day QVector sessions; qint64 d_first,d_last; private: diff --git a/SleepLib/machine.h b/SleepLib/machine.h index c02d5b53..974759b3 100644 --- a/SleepLib/machine.h +++ b/SleepLib/machine.h @@ -33,6 +33,9 @@ class Session; class Profile; class Machine; +/*! \class SaveThread + \brief This class is used in the multithreaded save code.. It accelerates the indexing of summary data. + */ class SaveThread:public QThread { Q_OBJECT @@ -48,36 +51,81 @@ signals: }; +/*! \class Machine + \brief This Machine class is the Heart of SleepyLib, representing a single Machine and holding it's data + + */ class Machine { public: + /*! \fn Machine(Profile *p,MachineID id=0); + \brief Constructs a Machine object in Profile p, and with MachineID id + + If supplied MachineID is zero, it will generate a new unused random one. + */ Machine(Profile *p,MachineID id=0); virtual ~Machine(); + //! \brief Load all Machine summary data bool Load(); + //! \brief Save all Sessions where changed bit is set. bool Save(); + + //! \brief Save individual session bool SaveSession(Session *sess); + + //! \brief Deletes the crud out of all machine data in the SleepLib database bool Purge(int secret); + //! \brief Contains a secondary index of day data, containing just this machines sessions QMap day; + + //! \brief Contains all sessions for this machine, indexed by SessionID QHash sessionlist; + + //! \brief List of text machine properties, like brand, model, etc... QHash properties; + //! \brief Returns a pointer to a valid Session object if SessionID exists Session * SessionExists(SessionID session); + + //! \brief Adds the session to this machine object, and the Master Profile list. (used during load) Day *AddSession(Session *s,Profile *p); + //! \brief Sets the Class of machine (Used to reference the particular loader that created it) void SetClass(QString t) { m_class=t; } + + //! \brief Sets the type of machine, according to MachineType enum void SetType(MachineType t) { m_type=t; } + + //! \brief Returns the Class of machine (Used to reference the particular loader that created it) const QString & GetClass() { return m_class; } + + //! \brief Returns the type of machine, according to MachineType enum const MachineType & GetType() { return m_type; } + + //! \brief Returns the machineID as a lower case hexadecimal string QString hexid() { return QString().sprintf("%08lx",m_id); } + + + //! \brief Unused, increments the most recent sessionID SessionID CreateSessionID() { return highest_sessionid+1; } + + //! \brief Returns this objects MachineID const MachineID & id() { return m_id; } + + //! \brief Returns the date of the first loaded Session const QDate & FirstDay() { return firstday; } + + //! \brief Returns the date of the most recent loaded Session const QDate & LastDay() { return lastday; } + //! \brief Grab the next task in the multithreaded save code Session *popSaveList(); + + //! \brief The list of sessions that need saving (for multithreaded save code) QList m_savelist; + volatile int savelistCnt; int savelistSize; QMutex savelistMutex; @@ -95,6 +143,10 @@ protected: bool firstsession; }; + +/*! \class CPAP + \brief A CPAP classed machine object.. These are only really for show + */ class CPAP:public Machine { public: @@ -102,6 +154,10 @@ public: virtual ~CPAP(); }; + +/*! \class Oximeter + \brief An Oximeter classed machine object.. These are only really for show + */ class Oximeter:public Machine { public: @@ -110,6 +166,9 @@ public: protected: }; +/*! \class SleepStage + \brief A SleepStage classed machine object.. These are only really for show + */ class SleepStage:public Machine { public: @@ -118,6 +177,7 @@ public: protected: }; +//! \brief Calculate the timezone Offset in milliseconds between system timezone and UTC qint64 timezoneOffset(); #endif // MACHINE_H diff --git a/SleepLib/session.cpp b/SleepLib/session.cpp index d846d709..ebe4d18e 100644 --- a/SleepLib/session.cpp +++ b/SleepLib/session.cpp @@ -960,15 +960,15 @@ EventDataType Session::wavg(ChannelID id) return v; } -EventList * Session::AddEventList(QString chan, EventListType et,EventDataType gain,EventDataType offset,EventDataType min, EventDataType max,EventDataType rate,bool second_field) +EventList * Session::AddEventList(ChannelID code, EventListType et,EventDataType gain,EventDataType offset,EventDataType min, EventDataType max,EventDataType rate,bool second_field) { - schema::Channel * channel=&schema::channel[chan]; + schema::Channel * channel=&schema::channel[code]; if (!channel) { qWarning() << "Channel" << chan << "does not exist!"; //return NULL; } EventList * el=new EventList(et,gain,offset,min,max,rate,second_field); - eventlist[chan].push_back(el); + eventlist[code].push_back(el); //s_machine->registerChannel(chan); return el; } diff --git a/SleepLib/session.h b/SleepLib/session.h index d51bb2cb..23b0304d 100644 --- a/SleepLib/session.h +++ b/SleepLib/session.h @@ -18,44 +18,81 @@ //class EventList; class Machine; +/*! \class Session + \brief Contains a single Sessions worth of machine event/waveform information. + This class also contains all the primary database logic for SleepLib + */ class Session { public: + /*! \fn Session(Machine *,SessionID); + \brief Create a session object belonging to Machine, with supplied SessionID + If sessionID is 0, the next in sequence will be picked + */ Session(Machine *,SessionID); virtual ~Session(); + //! \brief Stores the session in the directory supplied by path bool Store(QString path); + + //! \brief Writes the Sessions Summary Indexes to filename, in SleepLibs custom data format. bool StoreSummary(QString filename); + + //! \brief Writes the Sessions EventLists to filename, in SleepLibs custom data format. bool StoreEvents(QString filename); + //bool Load(QString path); + + //! \brief Loads the Sessions Summary Indexes from filename, from SleepLibs custom data format. bool LoadSummary(QString filename); + + //! \brief Loads the Sessions EventLists from filename, from SleepLibs custom data format. bool LoadEvents(QString filename); + //! \brief Loads the events for this session when requested (only the summaries are loaded at startup) bool OpenEvents(); + + //! \brief Put the events away until needed again, freeing memory void TrashEvents(); + //! \brief Search for Event code happening within dist milliseconds of supplied time (ms since epoch) bool SearchEvent(ChannelID code, qint64 time, qint64 dist=15000); - + //! \brief Return the sessionID const SessionID & session() { return s_session; } + + //! \brief Return the start of this sessions time range (in milliseconds since epoch) qint64 first() { return s_first; } + + //! \brief Return the end of this sessions time range (in milliseconds since epoch) qint64 last() { return s_last; } + + //! \brief Return the millisecond length of this session qint64 length() { return s_last-s_first; } + + //! \brief Set this Sessions ID (Not does not update indexes) void SetSessionID(SessionID s) { s_session=s; } + + //! \brief Moves all of this session data by offset d milliseconds void offsetSession(qint64 d); + + //! \brief Just set the start of the timerange without comparing void really_set_first(qint64 d) { s_first=d; } + + //! \brief Just set the end of the timerange without comparing void really_set_last(qint64 d) { s_last=d; } + void set_first(qint64 d) { if (!s_first) s_first=d; else if (d > eventlist; + + //! \brief Sessions Settings List, contianing single settings for this session. QHash settings; + + // Session caches QHash m_cnt; QHash m_sum; QHash m_avg; @@ -112,36 +158,74 @@ public: int count(ChannelID id); + //! \brief Returns the Count of all events of type id between time range int rangeCount(ChannelID id, qint64 first,qint64 last); + + //! \brief Returns the Sum of all events of type id between time range double rangeSum(ChannelID id, qint64 first,qint64 last); + + //! \brief Returns the minimum of events of type id between time range EventDataType rangeMin(ChannelID id, qint64 first,qint64 last); + + //! \brief Returns the maximum of events of type id between time range EventDataType rangeMax(ChannelID id, qint64 first,qint64 last); + + //! \brief Returns (and caches) the Sum of all events of type id double sum(ChannelID id); + + //! \brief Returns (and caches) the Average of all events of type id EventDataType avg(ChannelID id); + + //! \brief Returns (and caches) the Time Weighted Average of all events of type id EventDataType wavg(ChannelID i); + + //! \brief Returns (and caches) the Minimum of all events of type id EventDataType Min(ChannelID id); + + //! \brief Returns (and caches) the Maximum of all events of type id EventDataType Max(ChannelID id); + + //! \brief Returns (and caches) the 90th Percentile of all events of type id EventDataType p90(ChannelID id); + + //! \brief Returns (and caches) the Count-Per-Hour of all events of type id EventDataType cph(ChannelID id); + + //! \brief Returns (and caches) the Sum-Per-Hour of all events of type id EventDataType sph(ChannelID id); + //! \brief Returns (without caching) the requested Percentile of all events of type id EventDataType percentile(ChannelID id,EventDataType percentile); + //! \brief Returns true if the channel has events loaded, or a record of a count for when they are not bool channelExists(QString name);// { return (schema::channel.names.contains(name));} bool IsLoneSession() { return s_lonesession; } void SetLoneSession(bool b) { s_lonesession=b; } + + //! \brief Sets the event file linked to the summary (during load, for ondemand loading) void SetEventFile(QString & filename) { s_eventfile=filename; } + //! \brief Update this sessions first time if it's less than the current record inline void updateFirst(qint64 v) { if (!s_first) s_first=v; else if (s_first>v) s_first=v; } + + //! \brief Update this sessions latest time if it's more than the current record inline void updateLast(qint64 v) { if (!s_last) s_last=v; else if (s_last +//! \brief Gets the first day of week from the system locale, to show in the calendars. Qt::DayOfWeek firstDayOfWeekFromLocale(); + +//! \brief Delay of ms milliseconds void sh_delay(int ms); #endif