StopWatch.h

Go to the documentation of this file.

#pragma once
 
// Macro per sovvertire alla presenza dell'enumerazione 'WorkingState' nella classe CORE "StopWatchData", alla quale l'utente non 
// deve avere accesso
/*
L'utente deve poter utilizzare l'enumerazione degli stati 'WorkingState' come se fosse definita all'interno del WRAPPER "StopWatch".
Questo è più complicato dato dal fatto che l'enumerazione, per la logica sulla quale si basa il progetto, si trova nel CORE "StopWatchData"
[classe] alla quale l'utente non ha accesso.
Per "risolvere" questo inconvenite risulta "comodo" "ingannare l'utente" "facendoli sembrare" che l'enumerazione si trovi nel WRAPPER "StopWatch".
Altri metodi potrebbero prevedere la riformulazione totale della logica base sulla quale si basa il progetto.
In questo caso, però, avendo sia CORE e corrispondente WRAPPER, risulta più logico definire tutte le eventuali enumerazioni nel CORE.
Il WRAPPER fungerà solamente da TRAMITE e INTERPRETE tra utente e codice.
*/
#define StopWatch__WorkingState StopWatchData::WorkingState
 
/*
Relazioni tra WRAPPER e CORE:
l'utente deve essere a conoscenza solamente del WRAPPER costruito "attorno" al CORE.
L'invalidatore del CORE, nominato 'CoreInvalidator' serve solamente per regolare l'invalidatore del WRAPPER.
L'utente deve avere in ritorno e occuparsi solamente dell'invalidatore del WRAPPER.
*/
 
#pragma region INCLUSIONS
// Classe per la gestione dell'oggetto CRONOMETRO
/*
Classe di autori 'Grandieri Andrea', 'Barsotti Mirko', 'Erba Lorenzo' rappresentante l'oggetto CRONOMETRO e tutti gli attributi
e i metodi associati.
*/
#include "StopWatchData.h"
#pragma endregion INCLUSIONS
 
// Namespace di protezione dalle inclusioni multiple con nominazione uguale
/*
I valori constexpr, come spiegato appena sopra, equivalgono alla direttiva '#define'. Questo può creare problemi nel momento in cui un singolo file viene incluso
in una gerarchia di molti più file, dove si potrebbe riscontrare la presenza di constexpr appartenenti a file diversi ma con gli stessi nomi! Questa ripetitività dei nomi deriva
dagli standard di nominazione. Per evitare, quindi, conflitti di multipla definizione, andremo ad utilizzare un 'namespace', che, come dice il nome, fornisce uno SPAZIO per i NOMI del nostro
file in cui il 'namespace' è stato dichiarato ed implementato.
Mantieniamo comunque la specificazione 'static', per evitare errori di linker in caso di inclusioni multiple di questa unità di traslazione [file].
*/
namespace StopWatch__file
{
    // Valore costante che viene ritornato in caso di invalidità riscontrata nell'oggetto durante il dereferenziamento
    // per la chiamata dei metodi.
    // Il valore invalido utilizzato è un valore impossibile, cioè che non potrebbe essere mai restituito naturalmente.
    static constexpr int _invalidvalue = -1;
}
 
class StopWatch
{
    /*Blocco trivial*/
    /*
    Stiamo trattando una classe interamente statica. Per la definizione di staticit�, descritta successivamente, questa classe funger� solamente
    da "contenitore astratto" per organizzare pi� logicamente i dati. In verit�, tutto risieder� principalmente nel Data Segment, quindi sar�
    globale, ma statico (anche questo descritto successivamente).
    Questa staticit� implica la NON necessit� di creare istanze di questa classe, che risulterebbero totalmente inutili dato che tutti gli attributi
    e i metodi esistono nell'ambito globale.
    Per evitare, quindi, inutili istanziamenti, verranno bloccati il costruttore trivial (di default generato dal compilatore) e il distruttore, reso
    inutile dalla non-istanziabilit� della classe stessa.
    */
private:
    // Blocco attraverso privatizzazione del costruttore trivial
    StopWatch() = default;
    // Blocco attraverso privatizzazione del distruttore trivial
    ~StopWatch() = default;
 
    /*Attributi*/
private:
    // Puntatore all'oggetto cronometro di classe "StopWatchData"
    /*
    Questa variabile conterrà l'istanza dell'oggetto di classe "StopWatchData" creata durante l'operazione di inizializzazione.
    Questo oggetto rappresenta un vero e proprio cronometro. Fornisce tutti i metodi necessari alla sua gestione e ritorna il valore della
    'constexpr' '_invalidvalue' per comunicare genericamente errori.
    L'oggetto sar� sottoposto ad allocazione dinamica [heap]. Questo per evitare problemi con la deallocazione mirata all'ambito
    caratteristica della memoria statica [stack]. Una allocazione statica [stack] provocherebbe l'allocazione e successiva deallocazione
    immediata dell'oggetto esistendo solamente nell'ambito di inizializzazione.
    Essendo statica, la variabile (puntatore) verr� allocata nel 'Data Segment' (segmento dei dati) ed "esister�" fino a termine
    del programma stesso. Quindi si tratta di una variabile globale, ma statica. Questo la rende esistente solamente in questa unit�
    di traslazione (file).
    */
    static StopWatchData* m_StopWatch;
 
    /*Init*/
public:
    // Inizializza il cronometro con il rispettivo costruttore.
    /*
    Questo metodo, fondamentale, "dà vita" al cronometro. Effettua una allocazione (dinamica [heap]) attraverso il rispettivo costruttore della classe
    "StopWatchData".
    Analizzando questo costruttore, notiamo come non accetti nessun parametro. Possiamo quindi trattarlo come un costruttore di default.
    Il metodo ritorna un valore booleano, utilizzato per comunicare eventuali errori durante l'allocazione.
    Inoltre, prima dell'effettiva allocazione, esegue una deallocazione [delete] se necessaria.
    Anche qua ritroviamo la specificazione di staticità. Nel caso di applicazione ad un metodo, dissocia il metodo stesso da qualsiasi possibile istanza
    della classe. Quindi, il metodo sarà richiamabile come se fosse globale (e statico). Sarà solamente necessario anteporre il nome della classe di
    appartenenza. Ricordiamo anche che i metodi statici possono operare solo su variabili statiche, che anch'esse, essendo globali (e statiche) sono
    totalmente dissociate da possibili istanze della classe stessa (da oggetti).
    */
    static bool Init();
 
    /*Service Management*/
public:
    // Avvia il cronometro
    /*
    Questo metodo semplicemente avvia il cronometro. 
    Per fare ciò, effettua una chiamata ad uno specifico metodo di avvio implementato nella classe "StopWatchData".
    Restitusce un valore booleano per comunicare il corretto avvio 'true' oppure no 'false'
    Permette quindi, la gestione ad alto livello lasciata all'utente.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static bool Start();
 
    // Arresta il cronometro
    /*
    Questo metodo semplicemente arresta il cronometro.
    Per fare ciò, effettua una chiamata ad uno specifico metodo di arresto implementato nella classe "StopWatchData"
    Restituisce un valore booleano per comunicare il corretto arresto 'true' oppure no 'false'
    Permette quindi, la gestione ad alto livello lasciata all'utente.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static bool Stop();
 
    // Resetta il cronometro 
    // Procede all'operazione attraverso una reallocazione
    /*
    Questo metodo resetta il cronometro, riportandolo allo stato "di zero".
    Per fare ciò, NON utilizza metodi presenti nella classe "StopWatchData". In effetti, controllando la documentazione
    della classe "StopWatchData" si può notare come il 'reset' sia implementato come una semplice creazione di una 
    nuova istanza cronometro.
    Quindi, per fare ciò, effettueremo una nuova allocazione. Il metodo 'Init' della classe "StopWatch" gestirà la presenza
    al massimo di un cronometro, deallocando il precedente.
    Il metodo restituisce un valore booleano per comunicare il corretto reset 'true' oppure no 'false'
    Permette quindi, la gestione ad alto livello lasciata all'utente.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static bool Reset();
 
    /*LowLevel getters*/
    /*
    I seguenti metodi LowLevel sono supposti soprattutto per uso a scopo di debug e management manuale.
    Forniscono un punto di accesso costante a VALORE MODIFICABILE (quindi dereferenziabile ma non reindirizzabile).
    In release mode, potrebbe risultare efficace cambiare il contrassegno da 'public' a 'private'.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
public:
    // Ritorna un puntatore all'oggetto di classe "StopWatchData"
    static StopWatchData* const get_StopWatch();
 
    /*LowLevel reallocator*/
    // In questo caso, non è necessaria l'implementazione essendo equivalente al metodo 'Init'
 
    /*Metodi*/
public:
    // Restituisce il valore del cronometro
    /*
    Questo metodo rappresenta il principale scopo della classe: ottenere il valore del cronometro.
    Il tipo restituito è 'String' [stringa]. Il formato dei valori è --> 'hh:mm:ss'
    Il metodo restituisce il valore della 'constexpr' '_invalidvalue' per comunicare eventuali generici errori.
    Permette quindi, la gestione ad alto livello lasciata all'utente.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static String get_CurrentFormattedStopWatch();
 
    // Restituisce lo stato attuale del cronometro
    /*
    Questo metodo permette di ottenere come valore di ritorno lo stato attuale del cronometro.
    Sono possibili 2 stati:
    'WorkingState::OFFLINE' --> il cronometro non è in funzione
    'WorkingState::ONLINE' --> il cronometro è in funzione
 
    Questo metodo, appartenendo al WRAPPER, deve anche gestire eventuali stati INVALIDI, causati da un dereferenziamento impossibile
    a causa di una mancata allocazione iniziale.
    Per tale motivo, questo metodo potrà ritornare un altro stato, creato appositamente per queste occasioni nella enum class del CORE.
    Lo stato --> 'WorkingState::INVALID'.
    Molto importante è anche precisare l'impossibilità per il metodo di ritornare una 'reference [&]'. Questo, perchè, lo stato 'WorkingState::INVALID' viene ritornato
    direttamente come un valore numerico, un RVALUE!! Questo è causato dall'impossibilità di chiamare il corrispettivo metodo 'get_WorkingState' della classe "StopWatchData".
    */
    static const StopWatchData::WorkingState get_WorkingState();
 
    // Controlla la disponibilità di una connessione Internet. In caso negativo, effettua il reset di sicurezza del valore del cronometro
    static void Trigger_to_Check();
 
    /*Invalidator*/
    /*
    L'invalidatore consiste in quel valore che viene ritornato ogni qualvolta una chiamata da parte dell'utente ai metodi non produce il risultato atteso.
    E' importante specificare che, l'invalidatore, pur essendo costante, non deve essere dichiarato come 'constexpr' perchè NON deve seguire le regole di
    comportamento della direttiva '#define'. Il compilatore NON deve sostituire il nome dell'attributo con un valore numerico costante --> i.e. RVALUE!!
    L'invalidatore deve essere un vero e proprio attributo della classe, che però non deve mai appartenere ad uno specifico oggetto. Per questo deve essere sempre
    specificato come statico. Ovviamente, avrà una locazione nel Data Segment, sarà quindi globale ma statico (valido sono in questa unità di traslazione (file)) e utilizzabile
    solamente nell'ambito della classe di dichiarazione.
    */
    /*Attributo*/
private:
    // Valore costante che viene ritornato in caso di invalidità riscontrata nell'oggetto durante il dereferenziamento
    // per la chiamata dei metodi.
    // Il valore invalido utilizzato è un valore impossibile, cioè che non potrebbe essere mai restituito naturalmente.
    static const int m_Invalidator;
 
    /*getter*/
public:
    // Metodo per il ritorno del valore dell'Invalidatore. Verrà ritornata una referenza [reference --> '&'] costante, in modo tale da ottimizzare il processo e,
    // allo stesso tempo evitare modifiche inappropriate.
    /*
    Un'altra particolarità di questo metodo sta nel fatto che è definita come 'inline'. Questa keyword comunica al compilatore, ovunque trovi una chiamata
    a questo metodo, di NON effettuare una vera e propria chiamata, ma di sostituire la porzione del codice per la chiamata con il BODY del metodo (la implementazione stessa).
    Questa tecnica risulta molto utile per funzioni che effettuano pochissime operazioni e sono sottoposte a frequenti chiamate.
    Anche qua, per via della staticità, viene applicata la gestione analizzata prima.
    */
    static inline const int& get_Invalidator();
};
 
// Dichiarazione delle variabili GLOBALI STATICHE 
// Risiederanno nel Data Segment
/*
Essendo statiche in classe, tutti gli attributi non sono altro che variabili GLOBALI STATICHE.
Per questo è richiesta la dichiarazione globale. Non è necessario specificare 'static' essendo già stato specificato nella dichiarazione degli
attributi nella classe stessa.
*/
StopWatchData* StopWatch::m_StopWatch;
const int StopWatch::m_Invalidator = StopWatch__file::_invalidvalue;