[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]