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>

tcllib                                                 0.3                                  nameserv::auto(3tcl)