From 6b101463d9a20537e8d0453ee54f08cf837ffaf4 Mon Sep 17 00:00:00 2001 From: ribes Date: Thu, 1 Mar 2007 10:00:15 +0000 Subject: [PATCH] Doxygen documentation, english comment. --- src/DSC/DSC_Basic/DSC_interface.cxx | 128 ++++++++++------------------ src/DSC/DSC_Basic/DSC_interface.hxx | 27 ++++++ 2 files changed, 71 insertions(+), 84 deletions(-) diff --git a/src/DSC/DSC_Basic/DSC_interface.cxx b/src/DSC/DSC_Basic/DSC_interface.cxx index 324b4f6ad..faf266dbd 100644 --- a/src/DSC/DSC_Basic/DSC_interface.cxx +++ b/src/DSC/DSC_Basic/DSC_interface.cxx @@ -29,10 +29,6 @@ Engines_DSC_interface::Engines_DSC_interface() {} Engines_DSC_interface::~Engines_DSC_interface() {} -/* Ajoute le provides port "name" avec sa reference "ref". - * Lève PortAlreadyDefined si le port est déjà défini. - * Lève NilPort si la reference du port est nil. - */ void Engines_DSC_interface::add_provides_port(Ports::Port_ptr ref, const char* provides_port_name, @@ -41,7 +37,7 @@ throw (Engines::DSC::PortAlreadyDefined, Engines::DSC::NilPort, Engines::DSC::BadProperty) { - // Test des arguments de la méthode + // Method args test assert(provides_port_name); if (CORBA::is_nil(ref)) throw Engines::DSC::NilPort(); @@ -50,23 +46,20 @@ throw (Engines::DSC::PortAlreadyDefined, my_ports_it = my_ports.find(provides_port_name); if (my_ports_it == my_ports.end()) { - // Creation d'un nouveau port de type provides. + // Creating a new port provides port_t * new_port = new port_t(); new_port->type = provides; new_port->connection_nbr = 0; new_port->provides_port_ref = Ports::Port::_duplicate(ref); new_port->port_prop = Ports::PortProperties::_duplicate(port_prop); - // Enregistrement du port dans la map. + // Port into the port's map my_ports[provides_port_name] = new_port; } else throw Engines::DSC::PortAlreadyDefined(); } -/* Ajoute le uses port "name" avec son repository_id Corba. - * Lève PortAlreadyDefined si le port est déjà défini. - */ void Engines_DSC_interface::add_uses_port(const char* repository_id, const char* uses_port_name, @@ -74,9 +67,9 @@ Engines_DSC_interface::add_uses_port(const char* repository_id, throw (Engines::DSC::PortAlreadyDefined, Engines::DSC::BadProperty) { - // Test des arguments de la méthode - // Note : Il est difficile de tester si la chaîne du - // repository_id est valide ... + // Method args test + // Note : We can't be shure that repository id + // is a correct CORBA id. assert(repository_id); assert(uses_port_name); if (CORBA::is_nil(port_prop)) @@ -84,7 +77,7 @@ throw (Engines::DSC::PortAlreadyDefined, my_ports_it = my_ports.find(uses_port_name); if (my_ports_it == my_ports.end()) { - // Creation d'un nouveau port de type uses. + // Creating a new uses port port_t * new_port = new port_t(); new_port->type = uses; new_port->connection_nbr = 0; @@ -92,19 +85,13 @@ throw (Engines::DSC::PortAlreadyDefined, new_port->repository_id = repository_id; new_port->port_prop = Ports::PortProperties::_duplicate(port_prop); - // Enregistrement du port dans la map. + // Port into port's map my_ports[uses_port_name] = new_port; } else throw Engines::DSC::PortAlreadyDefined(); } -/* Fournit le port provides qui a le nom "provides_port_name" dans les my_ports. - * Lève l'exception Engines::DSC::PortNotDefined s'il ne trouve - * pas le port. - * Le booleen permet de savoir s'il faut donner ou non le port s'il est connecté - * ou non. - */ Ports::Port_ptr Engines_DSC_interface::get_provides_port(const char* provides_port_name, const CORBA::Boolean connection_error) @@ -112,7 +99,7 @@ Engines_DSC_interface::get_provides_port(const char* provides_port_name, Engines::DSC::PortNotConnected, Engines::DSC::BadPortType) { - // Test des arguments de la méthode + // Method arg test assert(provides_port_name); Ports::Port_ptr rtn_port = Ports::Port::_nil(); @@ -122,7 +109,8 @@ Engines_DSC_interface::get_provides_port(const char* provides_port_name, // for(it=my_ports.begin();it!=my_ports.end();++it) // std::cout << "|"<<(*it).first<<"|, "; // std::cout << std::endl; - + + // Searching the port my_ports_it = my_ports.find(provides_port_name); if (my_ports_it == my_ports.end()) throw Engines::DSC::PortNotDefined(); @@ -140,22 +128,18 @@ Engines_DSC_interface::get_provides_port(const char* provides_port_name, return rtn_port; } -/* Fournit le port uses qui a le nom "uses_port_name" s'il existe et s'il est - * connecté. - * Dans le cas contraire lève les exceptions : - * PortNotDefined, PortNotConnected. - */ Engines::DSC::uses_port * Engines_DSC_interface::get_uses_port(const char* uses_port_name) throw (Engines::DSC::PortNotDefined, Engines::DSC::PortNotConnected, Engines::DSC::BadPortType) { - // Test des arguments de la méthode + // Method arg test assert(uses_port_name); Engines::DSC::uses_port * rtn_port = NULL; - // On commence par tester si le port existe + + // Searching the uses port my_ports_it = my_ports.find(uses_port_name); if (my_ports_it == my_ports.end()) throw Engines::DSC::PortNotDefined(); @@ -166,7 +150,7 @@ Engines_DSC_interface::get_uses_port(const char* uses_port_name) throw BPT; } - // On regarde maintenant si le port est connecté + // Is the port connected ? if (my_ports[uses_port_name]->connection_nbr > 0) { rtn_port = new Engines::DSC::uses_port(my_ports[uses_port_name]->uses_port_refs); } @@ -176,23 +160,14 @@ Engines_DSC_interface::get_uses_port(const char* uses_port_name) return rtn_port; } - -/* - * Cette méthode prévient par le biais de l'attribut connection_nbr - * que le port provides est connecté à un uses port de plus. - * Notons que pour le moment le provides_port n'a pas de référence sur le composant - * qui détient le uses port. Le modèle actuel considère que c'est au - * "framework" ou a l'application de gérer les connexions et les déconnexions. - * Il n'y a donc pas de callback entre deux ports connectés. - * - */ void Engines_DSC_interface::connect_provides_port(const char* provides_port_name) throw (Engines::DSC::PortNotDefined) { + // Method arg test assert(provides_port_name); - // Le port uses existe t'il ? + // Searching the provides port my_ports_it = my_ports.find(provides_port_name); if (my_ports_it == my_ports.end()) throw Engines::DSC::PortNotDefined(); @@ -200,22 +175,15 @@ Engines_DSC_interface::connect_provides_port(const char* provides_port_name) throw Engines::DSC::PortNotDefined(); - // Augmentation du nombre de connexions + // Adding a new connection my_ports[provides_port_name]->connection_nbr += 1; - // On prévient le code utilisateur + // User code is informed provides_port_changed(provides_port_name, my_ports[provides_port_name]->connection_nbr, Engines::DSC::AddingConnection ); } -/* Cette méthode permet d'ajouter une connexion à un port uses. - * Elle appelle ensuite une méthode abstraite que le composant doit - * implémenter afin d'être averti lorsque les connexions changent. - * En effet, l'utilisateur doit ensuite prendre le nouveau uses_port - * fournit dans le callback. - * - */ void Engines_DSC_interface::connect_uses_port(const char* uses_port_name, Ports::Port_ptr provides_port_ref) @@ -223,9 +191,13 @@ Engines_DSC_interface::connect_uses_port(const char* uses_port_name, Engines::DSC::BadPortType, Engines::DSC::NilPort) { + // Method arg test assert(uses_port_name); - // Le port uses existe t'il ? + if (CORBA::is_nil(provides_port_ref)) + throw Engines::DSC::NilPort(); + + // Searching the uses port my_ports_it = my_ports.find(uses_port_name); if (my_ports_it == my_ports.end()) throw Engines::DSC::PortNotDefined(); @@ -236,25 +208,20 @@ Engines_DSC_interface::connect_uses_port(const char* uses_port_name, throw BPT; } - // La reference est-elle nulle ? - if (CORBA::is_nil(provides_port_ref)) - throw Engines::DSC::NilPort(); - - // Le type est-il correct ? + // repository_id test const char * repository_id = my_ports[uses_port_name]->repository_id.c_str(); if (provides_port_ref->_is_a(repository_id)) { - // Ajout dans la sequence + // Adding provides port into the uses port sequence CORBA::ULong lgth = my_ports[uses_port_name]->uses_port_refs.length(); my_ports[uses_port_name]-> uses_port_refs.length(lgth + 1); my_ports[uses_port_name]->uses_port_refs[lgth] = Ports::Port::_duplicate(provides_port_ref); - // Augmentation du nombre de connexions + // Adding a new connection my_ports[uses_port_name]->connection_nbr += 1; - - // Appel du callback pour prévenir le uses port a été modifié + // User code is informed uses_port_changed(uses_port_name, new Engines::DSC::uses_port(my_ports[uses_port_name]->uses_port_refs), Engines::DSC::AddingConnection); @@ -269,23 +236,20 @@ Engines_DSC_interface::connect_uses_port(const char* uses_port_name, } -/* Cette méthode teste si le uses port "name" est connecté. - * Léve PortNotDefined si le port n'existe pas. - */ CORBA::Boolean Engines_DSC_interface::is_connected(const char* port_name) throw (Engines::DSC::PortNotDefined) { - assert(port_name); - CORBA::Boolean rtn = false; - // Le port existe t-il ? + // Method arg test + assert(port_name); + my_ports_it = my_ports.find(port_name); if (my_ports_it == my_ports.end()) throw Engines::DSC::PortNotDefined(); - // Le port est-il connecté ? + // Is it connected ? if (my_ports[port_name]->connection_nbr > 0) rtn = true; @@ -298,16 +262,16 @@ Engines_DSC_interface::disconnect_provides_port(const char* provides_port_name, throw (Engines::DSC::PortNotDefined, Engines::DSC::PortNotConnected) { + // Method args test assert(provides_port_name); - // Le port existe t-il ? my_ports_it = my_ports.find(provides_port_name); if (my_ports_it == my_ports.end()) throw Engines::DSC::PortNotDefined(); if (my_ports[provides_port_name]->type != provides) throw Engines::DSC::PortNotDefined(); - // Le port est-il connecté ? + // Is it connected ? if (my_ports[provides_port_name]->connection_nbr > 0) { my_ports[provides_port_name]->connection_nbr -= 1; @@ -327,22 +291,20 @@ throw (Engines::DSC::PortNotDefined, Engines::DSC::PortNotConnected, Engines::DSC::BadPortReference) { + // Method args test assert(uses_port_name); - // Le port existe t-il ? my_ports_it = my_ports.find(uses_port_name); if (my_ports_it == my_ports.end()) throw Engines::DSC::PortNotDefined(); if (my_ports[uses_port_name]->type != uses) throw Engines::DSC::PortNotDefined(); - // Le port est-il connecté ? - if (my_ports[uses_port_name]->connection_nbr > 0) { - // On cherche le port dans la sequence representant le - // uses port. - if (CORBA::is_nil(provides_port_ref)) - throw Engines::DSC::BadPortReference(); + if (CORBA::is_nil(provides_port_ref)) + throw Engines::DSC::BadPortReference(); + // Is it connected ? + if (my_ports[uses_port_name]->connection_nbr > 0) { CORBA::Long port_index = -1; CORBA::ULong seq_length = my_ports[uses_port_name]->uses_port_refs.length(); for(int i = 0; i < seq_length; i++) @@ -353,7 +315,6 @@ throw (Engines::DSC::PortNotDefined, break; } } - if (port_index == -1) throw Engines::DSC::BadPortReference(); @@ -379,11 +340,10 @@ throw (Engines::DSC::PortNotDefined, } } - // On remplace la sequence ... + // New uses port's sequence my_ports[uses_port_name]->uses_port_refs = *new_uses_port; - // Rq c'est à l'utilisateur de détruire - // la sequence s'il n'en veut pas !!! + // The user code is informed uses_port_changed(uses_port_name, new_uses_port, message); @@ -396,11 +356,11 @@ Ports::PortProperties_ptr Engines_DSC_interface::get_port_properties(const char* port_name) throw (Engines::DSC::PortNotDefined) { - assert(port_name); - Ports::PortProperties_ptr rtn_properties = Ports::PortProperties::_nil(); - // Le port existe t-il ? + // Method arg test + assert(port_name); + my_ports_it = my_ports.find(port_name); if (my_ports_it == my_ports.end()) throw Engines::DSC::PortNotDefined(); diff --git a/src/DSC/DSC_Basic/DSC_interface.hxx b/src/DSC/DSC_Basic/DSC_interface.hxx index 905d2ab4e..525843110 100644 --- a/src/DSC/DSC_Basic/DSC_interface.hxx +++ b/src/DSC/DSC_Basic/DSC_interface.hxx @@ -35,6 +35,9 @@ /*! \class Engines_DSC_interface * \brief This class implements the interface Engines::DSC + * + * This class is used by the sequential DSC implementation + * and the parallel DSC implementation. */ class Engines_DSC_interface: public DSC_Callbacks @@ -81,12 +84,20 @@ public: /*! * \see Engines::DSC::connect_provides_port + * + * \note This method uses Callbacks mechanism to inform the provides + * port how much uses ports are connected with. Currently, the provides + * port doesn't know its uses ports references. It's framework or application role + * to manage connections between ports. */ virtual void connect_provides_port(const char* provides_port_name) throw (Engines::DSC::PortNotDefined); /*! * \see Engines::DSC::connect_uses_port + * + * \note This method uses Callbacks mechanism to inform the uses + * port how much provides ports are connected with. */ virtual void connect_uses_port(const char* uses_port_name, Ports::Port_ptr provides_port_ref) @@ -102,6 +113,11 @@ public: /*! * \see Engines::DSC::disconnect_provides_port + * + * \note This method uses Callbacks mechanism to inform the provides + * port how much uses ports are connected with. Currently, the provides + * port doesn't know its uses ports references. It's framework or application role + * to manage connections between ports. */ virtual void disconnect_provides_port(const char* provides_port_name, const Engines::DSC::Message message) @@ -110,6 +126,14 @@ public: /*! * \see Engines::DSC::disconnect_uses_port + * + * + * \note This method uses Callbacks mechanism to inform the uses + * port how much provides ports are connected with. + * + * \warning The new sequence of the uses port is sended by the callback. + * The old sequence is not destoyed. Is uses port user's role to destroy + * the sequence. */ virtual void disconnect_uses_port(const char* uses_port_name, Ports::Port_ptr provides_port_ref, @@ -118,6 +142,9 @@ public: Engines::DSC::PortNotConnected, Engines::DSC::BadPortReference); + /*! + * \see Engines::DSC::get_port_properties + */ virtual Ports::PortProperties_ptr get_port_properties(const char* port_name) throw (Engines::DSC::PortNotDefined); -- 2.39.2