NAME

       nameserv::auto - Name service facility, Client Extension

SYNOPSIS

       package require Tcl  8.4

       package require nameserv::auto  ?0.3?

       package require nameserv

_________________________________________________________________________________________________

DESCRIPTION

       Please read the document Name service facility, introduction first.

       This  package  provides  the  exact  same API as is provided by package nameserv, i.e. the
       regular name service client. It differs from the former by taking measures to ensure  that
       longer-lived  data,  i.e. bound names, continuous and unfullfilled async searches, survive
       the loss of the connection to the name server as much as is possible.

       This means that the bound  names  and  continuous  and  unfullfilled  async  searches  are
       remembered  client-side  and  automatically re-entered into the server when the connection
       comes back after its loss. For bound names there  is  one  important  limitation  to  such
       restoration:  It  is  possible  that a name of this client was bound by a different client
       while the connection was gone. Such names are fully lost, and the best the package can and
       will do is to inform the user of this.

API

       The  user-visible  API  is  mainly  identical  to the API of nameserv and is therefore not
       described here. Please read the documentation of nameserv.

       The differences are explained below, in the sections OPTIONS and EVENTS.

OPTIONS

       This package supports all the options of package nameserv, plus one more.  The  additional
       option  allows  the  user  to specify the time interval between attempts to restore a lost
       connection.

       -delay milliseconds
              The value of this option is an integer value > 0 which specifies  the  interval  to
              wait  between  attempts  to restore a lost connection, in milliseconds. The default
              value is 1000, i.e. one second.

EVENTS

       This package generates all of the events of package nameserv, plus two more.  Both  events
       are generated for the tag nameserv.

       lost-name
              This event is generated when a bound name is truly lost, i.e. could not be restored
              after the temporary loss of the connection to the name server. It indicates that  a
              different client took ownership of the name while this client was out of contact.

              The  detail  information of the event will be a Tcl dictionary containing two keys,
              name, and data. Their values hold all the information about the lost name.

       re-connection
              This event is generated  when  the  connection  to  the  server  is  restored.  The
              remembered data has been restored when the event is posted.

              The event has no detail information.

DESIGN

       The  package  is  implemented  on  top  of  the  regular  nameservice client, i.e. package
       nameserv. It detects the loss of the connection by listening for  lost-connection  events,
       on the tag nameserv.

       It  reacts  to  such  events  by  starting a periodic timer and trying to reconnect to the
       server whenver this timer triggers. On success the  timer  is  canceled,  a  re-connection
       event  generated,  and  the  package  proceeds  to re-enter the remembered bound names and
       continuous searches.

       Another loss of  the  connection,  be  it  during  or  after  re-entering  the  remembered
       information simply restarts the timer and subsequent reconnection attempts.

BUGS, IDEAS, FEEDBACK

       This  document,  and  the  package  it  describes, will undoubtedly contain bugs and other
       problems.   Please  report  such  in  the  category  nameserv  of  the   Tcllib   Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be  made  by going to the Edit form of the ticket immediately after its creation, and then
       using the left-most button in the secondary navigation bar.

SEE ALSO

       nameserv(3tcl)

KEYWORDS

       automatic, client, name service, reconnect, restore

CATEGORY

       Networking

COPYRIGHT

       Copyright (c) 2007-2008 Andreas Kupries <andreas_kupries@users.sourceforge.net>