From 8265f289bd4944ea1c794b95b30c34312876bfae Mon Sep 17 00:00:00 2001 From: Thomas Harte Date: Mon, 19 Feb 2018 16:03:17 -0500 Subject: [PATCH] Improves documentation within the new parts. --- .../Implementation/MultiCRTMachine.hpp | 41 ++++++++++++++----- .../Implementation/MultiConfigurable.hpp | 7 ++++ .../MultiConfigurationTarget.hpp | 7 ++++ .../Implementation/MultiJoystickMachine.hpp | 8 +++- .../Implementation/MultiKeyboardMachine.hpp | 9 +++- .../Implementation/MultiSpeaker.hpp | 18 +++++++- .../Dynamic/MultiMachine/MultiMachine.hpp | 9 ++-- 7 files changed, 80 insertions(+), 19 deletions(-) diff --git a/Analyser/Dynamic/MultiMachine/Implementation/MultiCRTMachine.hpp b/Analyser/Dynamic/MultiMachine/Implementation/MultiCRTMachine.hpp index b82e1db53..b57583884 100644 --- a/Analyser/Dynamic/MultiMachine/Implementation/MultiCRTMachine.hpp +++ b/Analyser/Dynamic/MultiMachine/Implementation/MultiCRTMachine.hpp @@ -22,10 +22,37 @@ namespace Analyser { namespace Dynamic { -class MultiCRTMachine: public ::CRTMachine::Machine, public ::CRTMachine::Machine::Delegate { +/*! + Provides a class that multiplexes the CRT machine interface to multiple machines. + + Keeps a reference to the original vector of machines; will access it only after + acquiring a supplied mutex. The owner should also call did_change_machine_order() + if the order of machines changes. +*/ +class MultiCRTMachine: public CRTMachine::Machine, public CRTMachine::Machine::Delegate { public: MultiCRTMachine(const std::vector> &machines, std::mutex &machines_mutex); + /*! + Informs the MultiCRTMachine that the order of machines has changed; the MultiCRTMachine + uses this as an opportunity to synthesis any CRTMachine::Machine::Delegate messages that + are necessary to bridge the gap between one machine and the next. + */ + void did_change_machine_order(); + + /*! + Provides a mechanism by which a delegate can be informed each time a call to run_for has + been received. + */ + struct Delegate { + virtual void multi_crt_did_run_machines() = 0; + }; + /// Sets @c delegate as the receiver of delegate messages. + void set_delegate(Delegate *delegate) { + delegate_ = delegate; + } + + // Below is the standard CRTMachine::Machine interface; see there for documentation. void setup_output(float aspect_ratio) override; void close_output() override; Outputs::CRT::CRT *get_crt() override; @@ -35,19 +62,11 @@ class MultiCRTMachine: public ::CRTMachine::Machine, public ::CRTMachine::Machin bool get_clock_is_unlimited() override; void set_delegate(::CRTMachine::Machine::Delegate *delegate) override; + private: + // CRTMachine::Machine::Delegate void machine_did_change_clock_rate(Machine *machine) override; void machine_did_change_clock_is_unlimited(Machine *machine) override; - void did_change_machine_order(); - - struct Delegate { - virtual void multi_crt_did_run_machines() = 0; - }; - void set_delegate(Delegate *delegate) { - delegate_ = delegate; - } - - private: const std::vector> &machines_; std::mutex &machines_mutex_; std::vector queues_; diff --git a/Analyser/Dynamic/MultiMachine/Implementation/MultiConfigurable.hpp b/Analyser/Dynamic/MultiMachine/Implementation/MultiConfigurable.hpp index 8f00057e8..79695f5ad 100644 --- a/Analyser/Dynamic/MultiMachine/Implementation/MultiConfigurable.hpp +++ b/Analyser/Dynamic/MultiMachine/Implementation/MultiConfigurable.hpp @@ -17,10 +17,17 @@ namespace Analyser { namespace Dynamic { +/*! + Provides a class that multiplexes the configurable interface to multiple machines. + + Makes a static internal copy of the list of machines; makes no guarantees about the + order of delivered messages. +*/ class MultiConfigurable: public Configurable::Device { public: MultiConfigurable(const std::vector> &machines); + // Below is the standard Configurable::Device interface; see there for documentation. std::vector> get_options() override; void set_selections(const Configurable::SelectionSet &selection_by_option) override; Configurable::SelectionSet get_accurate_selections() override; diff --git a/Analyser/Dynamic/MultiMachine/Implementation/MultiConfigurationTarget.hpp b/Analyser/Dynamic/MultiMachine/Implementation/MultiConfigurationTarget.hpp index 886b6db40..374057333 100644 --- a/Analyser/Dynamic/MultiMachine/Implementation/MultiConfigurationTarget.hpp +++ b/Analyser/Dynamic/MultiMachine/Implementation/MultiConfigurationTarget.hpp @@ -18,10 +18,17 @@ namespace Analyser { namespace Dynamic { +/*! + Provides a class that multiplexes the configuration target interface to multiple machines. + + Makes a static internal copy of the list of machines; makes no guarantees about the + order of delivered messages. +*/ struct MultiConfigurationTarget: public ConfigurationTarget::Machine { public: MultiConfigurationTarget(const std::vector> &machines); + // Below is the standard ConfigurationTarget::Machine interface; see there for documentation. void configure_as_target(const Analyser::Static::Target &target) override; bool insert_media(const Analyser::Static::Media &media) override; diff --git a/Analyser/Dynamic/MultiMachine/Implementation/MultiJoystickMachine.hpp b/Analyser/Dynamic/MultiMachine/Implementation/MultiJoystickMachine.hpp index dad324354..137c96e95 100644 --- a/Analyser/Dynamic/MultiMachine/Implementation/MultiJoystickMachine.hpp +++ b/Analyser/Dynamic/MultiMachine/Implementation/MultiJoystickMachine.hpp @@ -17,16 +17,22 @@ namespace Analyser { namespace Dynamic { +/*! + Provides a class that multiplexes the joystick machine interface to multiple machines. + + Makes a static internal copy of the list of machines; makes no guarantees about the + order of delivered messages. +*/ class MultiJoystickMachine: public JoystickMachine::Machine { public: MultiJoystickMachine(const std::vector> &machines); + // Below is the standard JoystickMachine::Machine interface; see there for documentation. std::vector> &get_joysticks() override; private: std::vector machines_; std::vector> joysticks_; - }; } diff --git a/Analyser/Dynamic/MultiMachine/Implementation/MultiKeyboardMachine.hpp b/Analyser/Dynamic/MultiMachine/Implementation/MultiKeyboardMachine.hpp index 47df189a0..535fac6d1 100644 --- a/Analyser/Dynamic/MultiMachine/Implementation/MultiKeyboardMachine.hpp +++ b/Analyser/Dynamic/MultiMachine/Implementation/MultiKeyboardMachine.hpp @@ -18,10 +18,17 @@ namespace Analyser { namespace Dynamic { -class MultiKeyboardMachine: public ::KeyboardMachine::Machine { +/*! + Provides a class that multiplexes the keyboard machine interface to multiple machines. + + Makes a static internal copy of the list of machines; makes no guarantees about the + order of delivered messages. +*/ +class MultiKeyboardMachine: public KeyboardMachine::Machine { public: MultiKeyboardMachine(const std::vector> &machines); + // Below is the standard KeyboardMachine::Machine interface; see there for documentation. void clear_all_keys() override; void set_key_state(uint16_t key, bool is_pressed) override; void type_string(const std::string &) override; diff --git a/Analyser/Dynamic/MultiMachine/Implementation/MultiSpeaker.hpp b/Analyser/Dynamic/MultiMachine/Implementation/MultiSpeaker.hpp index 84d2c910a..cba1acca0 100644 --- a/Analyser/Dynamic/MultiMachine/Implementation/MultiSpeaker.hpp +++ b/Analyser/Dynamic/MultiMachine/Implementation/MultiSpeaker.hpp @@ -19,19 +19,33 @@ namespace Analyser { namespace Dynamic { +/*! + Provides a class that multiplexes calls to and from Outputs::Speaker::Speaker in order + transparently to connect a single caller to multiple destinations. + + Makes a static internal copy of the list of machines; expects the owner to keep it + abreast of the current frontmost machine. +*/ class MultiSpeaker: public Outputs::Speaker::Speaker, Outputs::Speaker::Speaker::Delegate { public: + /*! + Provides a construction mechanism that may return nullptr, in the case that all included + machines return nullptr as their speaker. + */ static MultiSpeaker *create(const std::vector> &machines); - MultiSpeaker(const std::vector &speakers); + /// This class requires the caller to nominate changes in the frontmost machine. void set_new_front_machine(::Machine::DynamicMachine *machine); + // Below is the standard Outputs::Speaker::Speaker interface; see there for documentation. float get_ideal_clock_rate_in_range(float minimum, float maximum); void set_output_rate(float cycles_per_second, int buffer_size); void set_delegate(Outputs::Speaker::Speaker::Delegate *delegate); - void speaker_did_complete_samples(Speaker *speaker, const std::vector &buffer); private: + void speaker_did_complete_samples(Speaker *speaker, const std::vector &buffer); + MultiSpeaker(const std::vector &speakers); + std::vector speakers_; Outputs::Speaker::Speaker *front_speaker_ = nullptr; Outputs::Speaker::Speaker::Delegate *delegate_ = nullptr; diff --git a/Analyser/Dynamic/MultiMachine/MultiMachine.hpp b/Analyser/Dynamic/MultiMachine/MultiMachine.hpp index 81feebef2..cf4711422 100644 --- a/Analyser/Dynamic/MultiMachine/MultiMachine.hpp +++ b/Analyser/Dynamic/MultiMachine/MultiMachine.hpp @@ -28,13 +28,15 @@ namespace Dynamic { Provides the same interface as to a single machine, while multiplexing all underlying calls to an array of real dynamic machines. - Calls to crt_machine->get_crt will return that for the first machine. + Calls to crt_machine->get_crt will return that for the frontmost machine; + anything installed as the speaker's delegate will similarly receive + feedback only from that machine. Following each crt_machine->run_for, reorders the supplied machines by confidence. If confidence for any machine becomes disproportionately low compared to - the others in the set, that machine is removed from the array. + the others in the set, that machine stops running. */ class MultiMachine: public ::Machine::DynamicMachine, public MultiCRTMachine::Delegate { public: @@ -47,10 +49,9 @@ class MultiMachine: public ::Machine::DynamicMachine, public MultiCRTMachine::De Configurable::Device *configurable_device() override; void *raw_pointer() override; + private: void multi_crt_did_run_machines() override; - - private: std::vector> machines_; std::mutex machines_mutex_;