nameserv(n)

💖 nameserv — Name service facility, Client 💖

okay so bestie, this is the client half of Tcllib's name service facility — the nameserv(n) page, part 1 of 2, so don't go anywhere. ✨

---

✨ SYNOPSIS ✨

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 🌸

Bestie, real talk: read Name service facility, introduction first. Like, actually. It's the prerequisite. No skipping, I'm watching. 👀

This package hands you a client for the name service facility — and that facility is implemented over in the package nameserv::server.

And important: this service is built on top of, and for, the package comm. It has literally nothing to do with the Internet's Domain Name System. Zero. None. If that's what you came for, go look at Tcllib's packages dns and resolv instead, bestie. Different vibe entirely. 💅

---

🎀 API 🎀

The package exports eight commands, and here they all are, one by one:

• ::nameserv::bind name data — Whoever calls this registers name as their name in the configured name service, and also tacks a piece of data onto it. The service does nothing with that info beyond storing it and handing it back as part of search results. What it means is entirely up to whatever apps are using the name service. A generally useful choice would be an identifier for a communication endpoint managed by the package comm — then anybody who retrieves the name can immediately talk to that endpoint, i.e. the registering application. Iconic, honestly.

Also important: a caller can register itself under more than one name, and each name gets its own piece of data. 🫶

Heads up: the name service — and therefore this command — will throw an error if the name you picked is already registered. Pick a better name, girl. 😭

• ::nameserv::release — Invoking this releases all names (and their data) registered by all previous ::nameserv::bind calls from this client. And note: the name service runs this command implicitly when it loses the connection to this client. So ghosting the server = auto-release. 💀
• ::nameserv::search ?-async|-continuous? ?pattern? — Searches the name service for every registered name matching the given glob-pattern. Don't specify one? It defaults to *, which matches everything. The result is a dictionary mapping the matching names to the data associated with them at bind-time.

But if you specified either -async or -continuous, the result changes — now it's the Tcl command of an object holding the actual result. These two options are supported if and only if the service you're connected to supports the protocol feature Search/Continuous. (Conditional queen. 👑)

• For -async, the result object gets asynchronously filled with the entries matching the pattern at the time of the search, and then it's frozen — never modified again.
• -continuous extends that by also continuously monitoring the service for additions and removals of entries matching the pattern, and updating the object's contents accordingly. Main character behaviour, fr fr.

Not me reminding you: the caller is responsible for configuring the object with a callback so you actually get notified when the current result (or further changes) arrive. Do it. Don't just stare at it. 🙈

For more on this object, see 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.
• ::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. Vibe check on your server. 🌈
• ::nameserv::cget -option — Returns the currently configured value for the specified -option. Supported options + what they mean = section OPTIONS.
• ::nameserv::configure — In this form, returns a dictionary of all supported options and their current values. Again, section OPTIONS.
• ::nameserv::configure -option — In this form, it's an alias for ::nameserv::cget -option. Section OPTIONS. You see the pattern. 😌
• ::nameserv::configure -option value... — In this form, you configure one or more of the supported options. At least one option has to be specified, and each option is followed by its new value. (Yes. Section OPTIONS.)

Big caveat, bestie: this form works only as long as the client hasn't contacted the name service yet. Once contact is 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 the first time one of the commands below runs — or whenever one of them runs after the connection was lost, when it was lost. Self-healing era. ✨

• bind
• release
• search
• server_protocol
• server_features

Since version 0.2 of the client, it generates an event when the connection is lost, so higher layers can do extra stuff. This happens via the support package uevent. This package — and all other name-service-related packages — hereby reserve the uevent-tag nameserv. All their events get posted to that tag. 🏷️

---

💜 EVENTS 💜

This package generates exactly one event: lost-connection. The detail information handed to that event is a Tcl dictionary. The only key in that dictionary is reason, and its value is a string describing why the connection was lost. That string is supplied by the underlying communication package, i.e. comm. So it's not us being vague — blame comm. 😭

---

⭐ OPTIONS ⭐

The options the client supports are all about which name service to contact, i.e. where that name service lives. Here they are:

• -host name|ipaddress — Specifies the host the name service you want to contact is running on, either by name or by ipaddress. The initial default is localhost, i.e. it expects to contact a name service running on the same host as the application using this package. Home sweet home. 🏠
• -port number — Specifies the port the name service you want 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. Default so cute you don't even have to think about it.

---

🌸 ASYNCHRONOUS AND CONTINUOUS SEARCHES 🌸

Asynchronous and continuous searches get invoked by passing either -async or -continuous as an argument to ::nameserv::search. Simple as that.

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 like, check your server's version before you get your hopes up. 🙈

For these searches, the result of the search command is the Tcl command of an object holding the actual result. The API these objects provide is:

🎀 Options 🎀

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

And like — sure, you could poll for the initial search result via the method filled, and poll for subsequent changes by comparing the output of getall against a saved copy. But that is not the recommended behaviour, bestie. Setting the -command callback and processing notifications as they arrive is much more efficient. Trust.

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 notification = the whole opening roster. 📋✨

🦋 Methods 🦋

• $result destroy — Destroys the object and cancels any continuous monitoring of the service the object may have had active. Bye bitch, respectfully. 💅
• $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. The origin story. 🌱

---

part 1 done, bestie — more parts are coming, don't close the tab 💖

🐛 BUGS, IDEAS, FEEDBACK 🐛

Okay bestie, real talk. This doc? And the whole package it's describing? It's gonna have bugs. And other problems. Like, undoubtedly. That's just the vibe of software, no cap. 😭

So if you find something cursed, please report it in the category nameserv of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. 🫶

And listen — if you have ideas for enhancements, for the package or for the documentation, those go there too. We want them. Both of them. All of them. 💖

---

🧚 Proposing code changes 🧚

When you're proposing code changes, you need to provide unified diffs, i.e. the output of:

diff -u

That's the format. That's the one. Don't be mysterious about it. ✨

⚠️ Also, heads up: attachments are strongly preferred over inlined patches. Like, strongly. Fr fr.

So how do you attach? Easy:

1. Create the ticket.
2. Immediately after it's created, go to the Edit form of that ticket.
3. Use the left-most button in the secondary navigation bar. That's the one. That's the door. 🚪✨

---

👀 SEE ALSO 👀

• nameserv::common(n)
• nameserv::server(n)

---

🔑 KEYWORDS 🔑

• client
• name service

---

🌈 CATEGORY 🌈

Networking

---

©️ COPYRIGHT ©️

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

---

okay that's the whole page bestie, we did it, we made it to the end 🎀

This one shipped out of tcllib, version 0.4.3, and it's the nameserv(n) page — so if you ever need to double-check which build you're reading, that's the little footprint it left at the bottom. No date on this one, just the version and the name. Slay. 💅✨ Go report a bug. Or fix one. Main character energy either way. 👑