The Level3 Internal Communications Design

1. The Level3 Internal Communications Design • Exports COM Interface: • class l3_hw_super_control { • perform_request ([in] BSTR cmd_xml, [out, retval] BSTR *error); • set_super_async_request_object ([in] l3_super_callback interface); • }; • Notes: • The set_super_async_request_object method’s interface is used by the Client (VRC) program to ask the super for control of the client by one of the independent control programs. The L3 Client Executable (VRC, ETG, Farm Node, etc.) l3_super_com L3 Comm Interface Library Main Program HW Control Client PCI L3 Super • Exports COM Interface: • class l3_super_callback { • relinquish_control ([in] BSTR id_string, [out, retval] BOOL *ok); • control_returned (); • }; • Exports COM Interface: • class l3_super_register { • add_machine ([in] BSTR machine_type, [in] BSTR machine_name, • [in] Il3_hw_super_control *callback, [in, out] BSTR *unique_name); • remove_machine ([in] BSTR unique_name); • }; • Exports C++ Interface: • class l3_super_com { • public: • l3_super_com (const std::string &machine_type, l3_client_callback *callback, const std::string &super_location = “”); • ~l3_super_com (void); • bool is_connected (void); • void connect (void); • void disconnect (void); • }; • Notes on Establishing the L3 Super – Client Connection: • L3 Super never looks for the Client • Upon boot of the Client program • The client program creates the l3_super_com object • the client will attempt a connection with Super every 30 seconds. • When the connection is made, it will give it the l3_hw_super_control object. • The super will then use that interface to give the client the l3_super_callback object. • The client will then tell the super it has control of the client if there is no one else that has connected in the mean time (using the control_returned method). • Otherwise, no one will have control (if the super can’t be found and connected to). • Exports C++ Interface: • class daq_hw_command_interface_base { • public: • virtual void perform_request (bool allowed_to_change_state, const std::string cmd_xml, std::string &err) = 0; • virtual void get_next_async_error (l3_internal_error &err) = 0; • virtual void cancel_async_error_wait (void) = 0; • }; Supervisor Interface • Notes: • This is the callback object that the l3 communications interface library uses to transmit super commands into the client application. • commands fed to perform_request are in an XML format. A subset of these commands will have to be clearly defined, as the Supervisor will need to synthesize them. However, the rest can be of arbitrary format. • perform_request is responsible for checking the command, determining if it will cause a state change, and then making sure it is allowed by looking at the allowed_to_change_state input argument. Appropriate error should be reported if they don’t match. Anything that might alter the course of a run in progress would be an example of a reason to require the allowed argument true. • control_request will block until the request is satisfied or fails. • get_next_async_error should block the calling thread until either an error is available, or the cancel_async_error_wait is called. • Requests for monitor information are fed through the perform_request method. • Exports COM Interface: • class l3_hw_direct_control { • perform_request ([in] BSTR cmd_xml, [out, retval] BSTR *error??); • request_control ([in] BSTR id_string, [out, retval] BOOL *have_control); • release_control ([in] BOOL reset_state); • has_control ([out, retval] BOOL *has_control); • who_has_control ([out, retval] BSTR *who); • }; • Notes: • Create this object to start the connection with the L3 supervisor (do it from any thread in your client program) • Pass the machine type (“VRC”, “ETG”, “FARM_NODE”, etc.) so the super knows what kind of program is running. • Pass in a pointer to the callback object; this is how commands from the super will be received. • The super location will default to d0l3super.fnal.gov. If you attempt to connect from a non-D0LEVEL3 domain computer you will fail security checks. • The connection will be established when the object is created, and killed when it is deleted. You can also control this using the connect and disconnect methods. • This object starts a separate thread that keeps track of the connection. It will attempt to reestablish the connection if it is dropped. • There is some provision for reconnecting without loosing state information, if that is useful. • Notes: • The perform_request method will send an arbitrary XML command. The communications layer outside will not interpret this command – it will be passed straight through to the HW control object. • The request_control method attempts to give this connection control of the Client. The id_string is an arbitrary string used to identify the person requesting control (so they can be identified by the DAQ shifters and others). It will first check to see if another independent control program already has control. Next, it will check to see if the supervisor is hooked up. If so, it will then ask it if control can be granted. If control can not be grabbed, it will return false. Check the who_has_control method to see who currently owns it. • If the supervisor needs control, but does not have it, it will report an error to the online system with the id_string of the person controlling the program. • Calling release_control or deleting this COM interface will give up control by this object. • If reset_state is true when release_control is called the supervisor assumes the machine is totally messed up and will reconfigured (from scratch). If it is set to false, then the supervisor will assume it is in the same state as when control was granted. Standalone Control Program(s) L3 Client Interface Stand alone Control Interface • Exports COM Interface: • class l3_client_monitor { • specify_monitor_interface ([in] montior_COM_interface, [in] int type_mask); • }; Independent Monitor • Exports COM Interface: • class l3_client_grabber { • monitor_item ([in] BSTR xml_error_info); • }; Independent Monitor Program (VB??) And L3 Monitor • Questions/Problems: • Need loose specification of the XML for generic errors, monitor events, and commands. • If super needs control back, there is no way to notify the independent control program (so it could either automatically give it back, or so that it could pop a dialog to warn the user). • Notes: • specify_monitor_interface is called with a mask that can limit the errors that are sent. For example, this means that the error monitor would only request errors/monitor info that is relatively high level. A special monitor program might want everything. • Errors that no one requests will be discarded.