core/Port.hh

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Copyright (c) 2000-2014 Ericsson Telecom AB
   3 // All rights reserved. This program and the accompanying materials
   4 // are made available under the terms of the Eclipse Public License v1.0
   5 // which accompanies this distribution, and is available at
   6 // http://www.eclipse.org/legal/epl-v10.html
   7 ///////////////////////////////////////////////////////////////////////////////
   8 #ifndef PORT_HH
   9 #define PORT_HH
  10
  11 #include <sys/types.h>
  12
  13 #include "Types.h"
  14 #include "Event_Handler.hh"
  15 #include <stddef.h> // only for NULL
  16
  17 class COMPONENT;
  18 class COMPONENT_template;
  19 class Text_Buf;
  20 class OCTETSTRING;
  21
  22 extern const COMPONENT_template& any_compref;
  23
  24 struct port_connection; // no user serviceable parts inside
  25
  26 /** Base class for all test ports */
  27 class PORT : public Fd_And_Timeout_Event_Handler {
  28   friend class PORT_LIST;
  29   friend struct port_connection;
  30
  31   static PORT *list_head, *list_tail;
  32
  33   void add_to_list();
  34   void remove_from_list();
  35   static PORT *lookup_by_name(const char *par_port_name);
  36
  37   struct port_parameter; // no user serviceable parts inside
  38   static port_parameter *parameter_head, *parameter_tail;
  39
  40   /** @brief Apply the given port parameter.
  41   *
  42   *  Applies the parameter to the appropriate port, or all ports if it's
  43   *  a parameter for all ports ( "*" )
  44   *  @param par_ptr pointer to the port parameter
  45   */
  46   static void apply_parameter(port_parameter *par_ptr);
  47   void set_system_parameters(const char *system_port);
  48
  49 public:
  50   struct msg_queue_item_base {
  51     struct msg_queue_item_base *next_item;
  52   };
  53   msg_queue_item_base *msg_queue_head, *msg_queue_tail;
  54 public:
  55   /** @brief Store a port parameter
  56   *
  57   *  @param component_id    component identifier
  58   *  @param par_port_name   string, name of the port, NULL if the parameter
  59   *                         refers to all ports ( "*" )
  60   *  @param parameter_name  string, name of the parameter
  61   *  @param parameter_value string, the value
  62   */
  63   static void add_parameter(const component_id_t& component_id,
  64     const char *par_port_name, const char *parameter_name,
  65     const char *parameter_value);
  66   /** Deallocates the list of port parameters */
  67   static void clear_parameters();
  68   /** @brief Apply port parameters to component
  69
  70   Iterates through all known port parameters and
  71
  72   @param component_reference
  73   @param component_name
  74   */
  75   static void set_parameters(component component_reference,
  76     const char *component_name);
  77
  78 protected:
  79   const char *port_name;
  80   unsigned int msg_head_count, msg_tail_count, proc_head_count,
  81   proc_tail_count;
  82   boolean is_active, is_started, is_halted;
  83
  84 private:
  85   int n_system_mappings;
  86   char **system_mappings;
  87   PORT *list_prev, *list_next;
  88   port_connection *connection_list_head, *connection_list_tail;
  89
  90 private:
  91   /// Copy constructor disabled.
  92   PORT(const PORT& other_port);
  93   /// Assignment disabled.
  94   PORT& operator=(const PORT& other_port);
  95
  96 public:
  97   PORT(const char *par_port_name);
  98   virtual ~PORT();
  99
 100   inline const char *get_name() const { return port_name; }
 101   void set_name(const char * name);
 102
 103   virtual void log() const;
 104
 105   void activate_port();
 106   void deactivate_port();
 107   static void deactivate_all();
 108
 109   void clear();
 110   static void all_clear();
 111   void start();
 112   static void all_start();
 113   void stop();
 114   static void all_stop();
 115   void halt();
 116   static void all_halt();
 117
 118   virtual alt_status receive(const COMPONENT_template& sender_template =
 119     any_compref, COMPONENT *sender_ptr = NULL);
 120   static alt_status any_receive(const COMPONENT_template& sender_template =
 121     any_compref, COMPONENT *sender_ptr = NULL);
 122   virtual alt_status check_receive(const COMPONENT_template&
 123     sender_template = any_compref, COMPONENT *sender_ptr = NULL);
 124   static alt_status any_check_receive(const COMPONENT_template&
 125     sender_template = any_compref, COMPONENT *sender_ptr = NULL);
 126
 127   virtual alt_status trigger(const COMPONENT_template& sender_template =
 128     any_compref, COMPONENT *sender_ptr = NULL);
 129   static alt_status any_trigger(const COMPONENT_template& sender_template =
 130     any_compref, COMPONENT *sender_ptr = NULL);
 131
 132   virtual alt_status getcall(const COMPONENT_template& sender_template =
 133     any_compref, COMPONENT *sender_ptr = NULL);
 134   static alt_status any_getcall(const COMPONENT_template& sender_template =
 135     any_compref, COMPONENT *sender_ptr = NULL);
 136   virtual alt_status check_getcall(const COMPONENT_template&
 137     sender_template = any_compref, COMPONENT *sender_ptr = NULL);
 138   static alt_status any_check_getcall(const COMPONENT_template&
 139     sender_template = any_compref, COMPONENT *sender_ptr = NULL);
 140
 141   virtual alt_status getreply(const COMPONENT_template& sender_template =
 142     any_compref, COMPONENT *sender_ptr = NULL);
 143   static alt_status any_getreply(const COMPONENT_template& sender_template =
 144     any_compref, COMPONENT *sender_ptr = NULL);
 145   virtual alt_status check_getreply(const COMPONENT_template&
 146     sender_template = any_compref, COMPONENT *sender_ptr = NULL);
 147   static alt_status any_check_getreply(const COMPONENT_template&
 148     sender_template = any_compref, COMPONENT *sender_ptr = NULL);
 149
 150   virtual alt_status get_exception(const COMPONENT_template&
 151     sender_template = any_compref, COMPONENT *sender_ptr = NULL);
 152   static alt_status any_catch(const COMPONENT_template& sender_template =
 153     any_compref, COMPONENT *sender_ptr = NULL);
 154   virtual alt_status check_catch(const COMPONENT_template&
 155     sender_template = any_compref, COMPONENT *sender_ptr = NULL);
 156   static alt_status any_check_catch(const COMPONENT_template&
 157     sender_template = any_compref, COMPONENT *sender_ptr = NULL);
 158
 159   alt_status check(const COMPONENT_template& sender_template = any_compref,
 160     COMPONENT *sender_ptr = NULL);
 161   static alt_status any_check(const COMPONENT_template& sender_template =
 162     any_compref, COMPONENT *sender_ptr = NULL);
 163
 164   /** Set a parameter on the port.
 165   *  @param parameter_name string
 166   *  @param parameter_value
 167   *
 168   *  The implementation in the PORT base class issues a warning and
 169   *  does nothing. Derived classes need to override this method.
 170   */
 171   virtual void set_parameter(const char *parameter_name,
 172     const char *parameter_value);
 173
 174   void append_to_msg_queue(msg_queue_item_base*);
 175 private:
 176   /** Callback interface for handling events - introduced in TITAN R7E
 177   * To use the finer granularity interface, this method must not be
 178   * overridden in the descendant Test Port class.
 179   * Note: Error event always triggers event handler call and is indicated in
 180   * the is_error parameter even if not requested.
 181   */
 182   virtual void Handle_Fd_Event(int fd,
 183     boolean is_readable, boolean is_writable, boolean is_error);
 184
 185   /** Callback interface for handling timeout - introduced in TITAN R7E
 186   * May not be overridden in the descendant Test Port class if
 187   * timeout is not used.
 188   */
 189   virtual void Handle_Timeout(double time_since_last_call);
 190
 191   /** Callback interface for handling events - introduced in TITAN R7E
 192   * These methods in the descendant Test Port class are called only if
 193   * Handle_Fd_Event is not overridden in the descendant Test Port class.
 194   * The method handling an event which is not used in the Test Port
 195   * may not be overridden in the descendant Test Port class.
 196   * This is true even for the error event handler, although error events
 197   * always trigger event handler call even if not requested.
 198   * (There is an empty default implementation for the error event handler.)
 199   */
 200   virtual void Handle_Fd_Event_Error(int fd);
 201   virtual void Handle_Fd_Event_Writable(int fd);
 202   virtual void Handle_Fd_Event_Readable(int fd);
 203
 204 public:
 205   /** Callback interface for handling events
 206   * This method is provided for Test Ports developed for TITAN versions
 207   * before R7E.
 208   * (It is called only if event handler has been registered with
 209   * Install_Handler.)
 210   */
 211   virtual void Event_Handler(const fd_set *read_fds, const fd_set *write_fds,
 212     const fd_set *error_fds, double time_since_last_call);
 213
 214 protected:
 215   /** Interface for handling events and timeout - introduced in TITAN R7E */
 216   typedef enum {
 217     EVENT_RD = FD_EVENT_RD, EVENT_WR = FD_EVENT_WR,
 218       EVENT_ERR = FD_EVENT_ERR,
 219       EVENT_ALL = FD_EVENT_RD | FD_EVENT_WR | FD_EVENT_ERR
 220   } Fd_Event_Type;
 221   void Handler_Add_Fd(int fd, Fd_Event_Type event_mask = EVENT_ALL);
 222   void Handler_Add_Fd_Read(int fd);
 223   void Handler_Add_Fd_Write(int fd);
 224   void Handler_Remove_Fd(int fd, Fd_Event_Type event_mask = EVENT_ALL);
 225   void Handler_Remove_Fd_Read(int fd);
 226   void Handler_Remove_Fd_Write(int fd);
 227   void Handler_Set_Timer(double call_interval, boolean is_timeout = TRUE,
 228     boolean call_anyway = TRUE, boolean is_periodic = TRUE);
 229
 230   /** Interface for handling events and timeout
 231   * This method is provided for Test Ports developed for TITAN versions
 232   * before R7E.
 233   */
 234   void Install_Handler(const fd_set *read_fds, const fd_set *write_fds,
 235     const fd_set *error_fds, double call_interval);
 236   /** Interface for handling events and timeout
 237   * This method is in use in Test Ports developed for TITAN versions
 238   * before R7E.
 239   * It can be used together with the interface introduced in TITAN R7E.
 240   */
 241   void Uninstall_Handler();
 242
 243   virtual void user_map(const char *system_port);
 244   virtual void user_unmap(const char *system_port);
 245
 246   virtual void user_start();
 247   virtual void user_stop();
 248
 249   virtual void clear_queue();
 250
 251   component get_default_destination();
 252
 253   static void prepare_message(Text_Buf& outgoing_buf,
 254     const char *message_type);
 255   static void prepare_call(Text_Buf& outgoing_buf,
 256     const char *signature_name);
 257   static void prepare_reply(Text_Buf& outgoing_buf,
 258     const char *signature_name);
 259   static void prepare_exception(Text_Buf& outgoing_buf,
 260     const char *signature_name);
 261   void send_data(Text_Buf& outgoing_buf,
 262     const COMPONENT& destination_component);
 263
 264   void process_data(port_connection *conn_ptr, Text_Buf& incoming_buf);
 265   virtual boolean process_message(const char *message_type,
 266     Text_Buf& incoming_buf, component sender_component, OCTETSTRING&);
 267   virtual boolean process_call(const char *signature_name,
 268     Text_Buf& incoming_buf, component sender_component);
 269   virtual boolean process_reply(const char *signature_name,
 270     Text_Buf& incoming_buf, component sender_component);
 271   virtual boolean process_exception(const char *signature_name,
 272     Text_Buf& incoming_buf, component sender_component);
 273
 274 private:
 275   port_connection *add_connection(component remote_component,
 276     const char *remote_port, transport_type_enum transport_type);
 277   void remove_connection(port_connection *conn_ptr);
 278   port_connection *lookup_connection_to_compref(component remote_component,
 279     boolean *is_unique);
 280   port_connection *lookup_connection(component remote_component,
 281     const char *remote_port);
 282   void add_local_connection(PORT *other_endpoint);
 283   void remove_local_connection(port_connection *conn_ptr);
 284
 285   static unsigned int get_connection_hash(component local_component,
 286     const char *local_port, component remote_component,
 287     const char *remote_port);
 288   static void unlink_unix_pathname(int socket_fd);
 289   void connect_listen_inet_stream(component remote_component,
 290     const char *remote_port);
 291   void connect_listen_unix_stream(component remote_component,
 292     const char *remote_port);
 293   void connect_local(component remote_component, const char *remote_port);
 294   void connect_stream(component remote_component, const char *remote_port,
 295     transport_type_enum transport_type, Text_Buf& text_buf);
 296   void disconnect_local(port_connection *conn_ptr);
 297   void disconnect_stream(port_connection *conn_ptr);
 298
 299   void send_data_local(port_connection *conn_ptr, Text_Buf& outgoing_data);
 300   boolean send_data_stream(port_connection *conn_ptr, Text_Buf& outgoing_data,
 301     boolean ignore_peer_disconnect);
 302
 303   void handle_incoming_connection(port_connection *conn_ptr);
 304   void handle_incoming_data(port_connection *conn_ptr);
 305   void process_last_message(port_connection *conn_ptr);
 306
 307   void map(const char *system_port);
 308   void unmap(const char *system_port);
 309
 310 public:
 311   static void process_connect_listen(const char *local_port,
 312     component remote_component, const char *remote_port,
 313     transport_type_enum transport_type);
 314   static void process_connect(const char *local_port,
 315     component remote_component, const char *remote_port,
 316     transport_type_enum transport_type, Text_Buf& text_buf);
 317   static void process_disconnect(const char *local_port,
 318     component remote_component, const char *remote_port);
 319   static void make_local_connection(const char *src_port,
 320     const char *dest_port);
 321   static void terminate_local_connection(const char *src_port,
 322     const char *dest_port);
 323
 324   static void map_port(const char *component_port, const char *system_port);
 325   static void unmap_port(const char *component_port, const char *system_port);
 326 };
 327
 328 #endif