nameserv(3tcl)

💖 NAME 💖

okay so bestie, this page is nameserv(3tcl), and it's all about nameserv — the Name service facility, Client. that's the whole vibe. it's the client half. the server half is a whole other page. 💅

---

✨ SYNOPSIS ✨

like, here's the whole shape of it:

package require Tcl 8.5 9

package require nameserv ?0.4.3?

package require comm

package require logger

::nameserv::bind name data

::nameserv::release

::nameserv::search ?-async|-continuous? ?pattern?

::nameserv::protocol

::nameserv::server_protocol

::nameserv::server_features

::nameserv::cget -option

::nameserv::configure

::nameserv::configure -option

::nameserv::configure -option value...

$result destroy

$result filled

$result get name

$result names

$result size

$result getall ?pattern?

---

🦋 DESCRIPTION 🦋

first things first, fr fr: please read Name service facility, introduction before you dive in here. it's giving prerequisite. 🌸

so this package hands you a client for the name service facility that's implemented by the package nameserv::server.

and now the part that lowkey matters: this service is built on top of and for the package comm. it has nothing to do with the Internet's Domain Name System, like zero, none, not a single thing. 🙈 if you're out here looking for a package that deals with that DNS, please go see Tcllib's packages dns and resolv instead. iykyk.

---

👑 API 👑

the package exports eight commands, and here they all are, no cap:

• ::nameserv::bind name data — the caller of this command registers the given name as its name in the configured name service, and also associates a piece of data with it. the service literally does nothing with this info beyond storing it and handing it back as part of search results. the meaning is entirely up to whatever applications are using the name service.

a generally useful choice would, for example, be an identifier for a communication endpoint managed by the package comm. anybody who retrieves the name becomes immediately able to talk to this endpoint, aka the registering application. slay.

also important: a caller can register itself under more than one name, and each name can have its own piece of data. main character energy, honestly.

note that the name service — and therefore this command — will throw an error if the chosen name is already registered. so pick your name, bestie, but pick one that's free. 💀

• ::nameserv::release — invoking this releases all names (and their data) registered by all previous calls to ::nameserv::bind made by this client. and heads up: the name service will run this command implicitly when it loses the connection to this client. it cleans up after you whether you asked or not. 🫶
• ::nameserv::search ?-async|-continuous? ?pattern? — this searches the name service for all registered names matching the specified glob-pattern. if you don't specify a pattern it defaults to *, which matches everything (we love a generous default ✨). the result of the command is a dictionary mapping the matching names to the data associated with them at bind-time.

if either option -async or -continuous was specified, the result of this command changes and becomes the Tcl command of an object holding the actual result. these two options are supported if and only if the service the client is connected to supports the protocol feature Search/Continuous. (vibe check your server first, okay?)

for -async, the result object is asynchronously filled with the entries matching the pattern at the time of the search, and then it is not modified any more. the option -continuous extends this behaviour by additionally continuously monitoring the service for the addition and removal of entries which match the pattern, and updating the object's contents appropriately. it's the difference between a screenshot and a livestream, periodt.

note that the caller is responsible for configuring the object with a callback for proper notification when the current result (or further changes) arrive. nobody's gonna tell you, babe, you gotta set it up.

for more info about this object, go see the section ASYNCHRONOUS AND CONTINUOUS SEARCHES. 👇

• ::nameserv::protocol — returns the highest version of the name service protocol supported by the package.
• ::nameserv::server_protocol — returns the highest version of the name service protocol supported by the name service the client is currently connected to. (different question, same energy.)
• ::nameserv::server_features — returns a list containing the names of the features of the name service protocol which are supported by the name service the client is currently connected to.
• ::nameserv::cget -option — returns the currently configured value for the specified -option. the full list of supported options and their meaning lives in the section OPTIONS. 🎀
• ::nameserv::configure — in this form, the command returns a dictionary of all supported options and their current values. again, list of supported options and their meaning → section OPTIONS.
• ::nameserv::configure -option — in this form the command is an alias for ::nameserv::cget -option. same list, same section, OPTIONS.
• ::nameserv::configure -option value... — in this form the command configures one or more of the supported options. you have to specify at least one option, and each option is followed by its new value. list of supported options and their meaning: you already know. OPTIONS. 💅

big one, don't skip it: this form can be used only as long as the client has not contacted the name service yet. after contact has been made, reconfiguration is not possible anymore. so this form is for initializing the client before it's used. the commands that force a contact with the name service are: bind release search server_protocol server_features

---

🔌 CONNECTION HANDLING 🔌

the client automatically connects to the service when one of the commands below is run for the first time — or whenever one of those commands is run after the connection was lost, when it was lost. it just... gets back up. resilient queen. 👑

bind

release

search

server_protocol

server_features

since version 0.2 of the client, it will generate an event when the connection is lost, which lets higher layers perform additional actions. this is done via the support package uevent. and this package, plus all other name service related packages, hereby reserves the uevent-tag nameserv. all their events will be posted to that tag. no takebacks. 🌈

---

🌟 EVENTS 🌟

this package generates exactly one event: lost-connection. the detail information provided to that event is a Tcl dictionary. the only key contained in that dictionary is reason, and its value will be a string describing why the connection was lost. that string is supplied by the underlying communication package, i.e. comm. so when the vibe dies, you at least get receipts. 😭

---

🎀 OPTIONS 🎀

the options supported by the client are all about specifying which name service to contact, i.e. the location of the name service. they are:

• -host name|ipaddress — this option specifies the host the name service to contact is running on, either by name, or by ipaddress. the initial default is localhost, i.e. it's expected to contact a name service running on the same host as the application using this package. staying local, as one does. 🏠
• -port number — this option specifies the port the name service to contact is listening on. it has to be a positive integer number (> 0) not greater than 65536 (unsigned short). the initial default is the number returned by the command ::nameserv::common::port, as provided by the package ::nameserv::common. cute default, honestly. ✨

---

🦋 ASYNCHRONOUS AND CONTINUOUS SEARCHES 🦋

asynchronous and continuous searches are invoked by using either option -async or -continuous as an argument to the command ::nameserv::search.

note that these two options are supported if and only if the service the client is connected to supports the protocol feature Search/Continuous. the service provided by the package ::nameserv::server does this since version 0.3. so if your server is ancient, this is not the moment. 🙈

for such searches, the result of the search command is the Tcl command of an object holding the actual result. the API provided by these objects is:

⭐ Options ⭐

• -command command_prefix — this option has to be set if a user of the result object wishes to get asynchronous notifications when the search result, or changes to it, arrive.

note that while it is possible to poll for the arrival of the initial search result via the method filled, and for subsequent changes by comparing the output of method getall against a saved copy, this is not the recommended behaviour. setting the -command callback and processing the notifications as they arrive is much more efficient. don't be out here refreshing like it's 2009, bestie. 💅

the command_prefix is called with two arguments: the type of change, and the data of the change. the type is either add or remove, indicating new data or deleted data, respectively. the data of the change is always a dictionary listing the added/removed names and their associated data.

the first change reported for a search is always the set of matching entries at the time of the search. first one's on the house. 🎁

💜 Methods 💜

• $result destroy — destroys the object and cancels any continuous monitoring of the service the object may have had active. bye bestie, cleanly. 👋
• $result filled — the result is a boolean value indicating whether the search result has already arrived (True), or not (False).
• $result get name — returns the data associated with the given name at bind-time.
• $result names — returns a list containing all names known to the object at the time of the invocation.
• $result size — returns an integer value specifying the size of the result at the time of the invocation.
• $result getall ?pattern? — returns a dictionary containing the search result at the time of the invocation, mapping the matching names to the data associated with them at bind-time. 🍓

---

🌸 HISTORY 🌸

• 0.3.1 — Fixed SF Bug 1954771.
• 0.3 — Extended the client with the ability to perform asynchronous and continuous searches.
• 0.2 — Extended the client with the ability to generate events when it loses its connection to the name service. Based on package uevent.
• 0.1 — Initial implementation of the client.

🐛 BUGS, IDEAS, FEEDBACK 💖

okay bestie, real talk for a sec 🫶 this doc, and the whole package it's describing, is absolutely gonna have bugs and other lil problems in it. that's just how software is, no cap. so if you find one, pls pls pls report it in the nameserv category of the Tcllib Trackers:

http://core.tcl.tk/tcllib/reportlist

and not just bugs, okay?? if you have ideas for enhancements for the package, or for the docs, or honestly for both — send those in too. we want them fr fr. ✨

when you're proposing code changes, pls give us unified diffs, i.e. the output of diff -u. that's the vibe. that's the format. 💅

also!! heads up: attachments are strongly preferred over inlined patches. like, strongly. so to attach one, go to the Edit form of the ticket right after you create it, and then hit the left-most button in the secondary navigation bar. that's the whole trick. 🎀

---

👀 SEE ALSO 👑

• nameserv::common(3tcl)
• nameserv::server(3tcl)

go read those too, they're part of the lore 🦋

---

🔑 KEYWORDS 🌸

• client
• name service

---

🌈 CATEGORY 🌈

Networking

---

©️ COPYRIGHT 💜

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

---

and that's the whole page, bestie, you made it to the end 🥳💖 this one was tcllib version 0.4.3, the nameserv(3tcl) page, and it's serving main character energy from start to finish. go forth and name-serve responsibly. periodt. 👑✨