Overview
| Artifact ID: | bd007833212f5ea958bff3a793224a4a26a28e3a |
|---|---|
| Ticket: | 481019ffffffffffffffffffffffffffffffffff |
| Date: | 2001-12-18 06:48:08 |
| User: | andreas_kupries |
| Artifact Attached: | be20d87cfb851136e80fd0a4126e728199377b57 |
| Filename: | registry.man |
| Description: | Manpage for a registry config package (doctools format) |
Content:
[manpage_begin registry n 1.0] [proc COMM {} {strong comm}] [proc COMMcfg {{fname {}}} {return [emph .tcl/comm/registry/$fname]}] [proc yesno {} {return [strong yes]|[strong no]}] [proc no {} {strong no}] [proc yes {} {strong yes}] [moddesc {Comm}] [titledesc {Registry configuration}] [require Tcl 8.2] [require comm::registry 0.1] [description] [para] This manpage specifies the interface to the configuration facilities of the [strong comm::registry] package. The actual launch and communication with said registry is done by the [COMM] package itself. [para] This setup allows the user of the registry client to configure the required behaviour first and then to launch the registry while loading the [COMM] core. [para] Both server and client code for the registry claim the directory [COMMcfg] in the home directory of the user running an application using [COMM] as place for configuration information and persistent state. [para] [strong Note:] Whenever the arguments [yesno] are present for a command the command will accept any boolean value recognized by the tcl interpreter itself. [list_begin definitions] [call [cmd ::comm::registry] [arg mode]] This command has to be called first when configuring the registry client. It determines the overall behaviour of the client. The following modes are available: [list_begin definitions] [lst_item [strong application]] The default mode for the client. It tells [COMM] that it is running in a regular application which talks to the actual registries. See section [strong APPLICATION] for more information. [lst_item [strong off]] Activate this mode for applications which want to use [COMM], but not the registry. Assume that the application knows to what other applications it wants to talk to, and where they are listening. [lst_item [strong leader]] Declares the calling application as the registry for a private circle of applications consisting of the calling application and its children. Use [cmd ::comm::registry::privacy] to declare if we will provide information from external registries to our children or not. See section [strong LEADER] for more information. [lst_item [strong registry]] Declares that the calling application is a registry. Additional configuration information determines its scope. See section [strong REGISTRY] for more information. [lst_item [strong proxy]] Declares that the calling application is a registry and also an application using other registries. See sections [strong APPLICATION] and [strong REGISTRY] on how to configure this mode. The application acts for its clients as a gateway to other registries. [list_end] [nl] For the modes [strong application] and [strong leader] the command will look in the directory [COMMcfg] for, read, and evaluate the following configuration files: [list_begin enum] [enum] [COMMcfg config] [enum] [COMMcfg config].[strong appname] [list_end] [nl] This makes it easy to setup and maintain global and application specific registry configurations outside of the applications themselves. The system assumes that the first file contains user specific configuration and that the second file contains application specific configuration. [nl] On unix the system will also look for [emph /etc/tcl/comm/config]. If that file exists it is read and evaluated before the other two files, and the system assumes that it contains host specific configuration information for applications. [nl] [strong {Please note that we currently have no specification for the location of host specific configuration information on windowas platforms. A possible place for such information would be the registry.}] [list_end] [para] In the following sections the various modes are described in more detail, together with the commands to configure them. [section APPLICATION] Usually an application talks only to one (standard) registry. This is the registry for the user executing the application. It can be a virtual registry spread over multiple hosts, if the user is executing applications on several machines sharing a single home directory. In that case the host-specifc registries for that user will cooperate to form a single virtual registry crossing machine boundaries. [para] The above behaviour can be changed however in several ways. [list_begin definitions] [call [cmd ::comm::registry::local]] Using this command restricts the usage of the standard registry to the applications registered for the same host this application is running on. [call [cmd ::comm::registry::add] [arg host] [arg port]] This command tells the client code to look for a registry running on the specified [arg host] and listening on the specified [arg port]. This is the standard mechanism for extending the search space of an application using [COMM]. [list_end] [para] It is expected that the commands above are placed into the user and application specific configuration files mentioned in the description of [cmd ::comm::registry::mode]. [para] [list_begin definitions] [call [cmd ::comm::registry::myServices] [arg list-of-service-names]] Beyond extending the search space for other applications we also have commands through which the currently running application provides more information about itself beyond the basic [strong name], [strong host], and [strong port]. [nl] This additional information is a list containing the names of the services provided by the application to other applications. [nl] [strong Note] that this module does [strong not] make any specification regarding the meaning of service names, nor about which commands have to go with each service. [list_end] [section LEADER] A leader is a regular application and all of the configuration information for such apply here too. [list_begin definitions] [call [cmd ::comm::registry::closed] [yesno]] When in mode [strong leader] an application using [COMM] is the registry for its children, i.e. the processes it has started. One of the decisions to make is whether the child processes only see themselves or not. The default is [yes], they see only themselves and their leader. [nl] If the closedness of the circle is set to [no] the leader will share all information it has about applications outside of the circle with the circle, i.e. its children, i.e. act as a proxy registry on their behalf to the outside world. [nl] The setting has no influence on the leader itself. This means that the leader will always see all applications registered with any registry the leader application is talking too. The setting only defines if the leader shares this information with its children or not. [nl] Closing the circle spawned by a leader is a bit more secure as the children have only a restricted view of the services available to them. [call [cmd ::comm::registry::proxy] [yesno]] The other decision a group leader has to make is whether it makes the information about its children available to the registries it is talking to or not. The default for this setting is [no], the information about the children is not given to the outside. [nl] If this flag is set to [yes] the leader will advertise its children to the outside registries so that they become available to other applications outside of the circle. [list_end] [para] The two settings for each of the two decisions lead to four possible combinations for a leader and its children: [list_begin definitions] [lst_item "closed, no proxy"] This is an isolated group of applications which talk to each other but not the outside. The exception is the leader which is still able to talk to other applications (Modulo the [strong application] settings). The children of the leader are invisible outside of the circle. [lst_item "open, no proxy"] This is a semi-isolated group of applications where the children and the leader see the outside world, but the outside world is not aware of the children, only of the leader (Modulo the [strong application] settings). [lst_item "closed, proxy"] This is a semi-isolated group of applications where the children and the leader are seen by the outside world, but the children are not aware of their environment, only of themselves and their leader. [lst_item "open, proxy"] The leader and its children are completely visible outside, and the outside is completely visible to alll applications in the circle. There is no real reason to have a leader, except maybe to better structure the communication between registries and applications. Another reason might be that the children depend on the leader and should go down with him. [list_end] [section REGISTRY] An application in [strong registry] mode is a registry, i.e. when loading [COMM] the system will not start the client code, but the server side. Configurable behaviour includes: [list_begin definitions] [call [cmd ::comm::registry::isStandard] [yesno]] Declares whether the registry is the standard registry for a user or independent. Default is [yes]. i.e. the registry is the standard registry. [call [cmd ::comm::registry::exitAfterLast] [yesno]] Declares, if the registry should exit after the last application is deregistered or not. Default is [yes]. [call [cmd ::comm::registry::exitDelay] [arg delay]] Declares a [arg delay] in seconds for the exit if the registry is configured to exit after the last application deregistered (see [cmd ::comm::registry::exitAfterLast]). Default is 0 seconds, i.e. no delay. [call [cmd ::comm::registry::acceptRemote] [yesno]] If the registry accepts registrations of applications not running on the localhost. Default is [no]. For a standard registry the other standard registries for the same user are exempt from this rule. [call [cmd ::comm::registry::port] [arg port]] Declares the specific port to have the registry listen on. Default is to let the OS select the port for a non-standard registry and to use the information in [COMMcfg [strong hostname]] for a standard registry. [list_end] [para] Which applications will know about a non-standard registry is dependent on the host-, user- and application-specific setup of the registry client, see section [strong APPLICATION]. It is not under influence of the registry server itself. [keywords manpage communication registry network internet] [manpage_end]