TSCONFIG(3ts)

💖 TSCONFIG FUNCTIONS (3ts) 💖

okay bestie, gather round, because this is the TSConfig API and it's genuinely one of the most iconic little safety nets in the whole Apache Traffic Server plugin toolkit. it lives in section 3ts, it's all about not blowing up your config mid-callback, and honestly? we're obsessed. ✨

---

🌸 NAME 🌸

TSConfig Functions — the TSConfig API function, periodt. 💅

---

🦋 SYNOPSIS 🦋

#include <ts/ts.h>

typedef void (*TSConfigDestroyFunc)(void*)

unsigned int TSConfigSet(unsigned int id, void *data,
TSConfigDestroyFunc funcp)

TSConfig TSConfigGet(unsigned int id)

void TSConfigRelease(unsigned int id, TSConfig configp)

void *TSConfigDataGet(TSConfig configp)

like, yes, that first typedef is missing its semicolon and no we are not fixing it, that's literally what's in the header. 🙈 copy it exactly or the vibe check fails.

---

👑 DESCRIPTION 👑

so here's the tea: these functions give you a mechanism to safely update configurations for a plugin. that's the whole assignment. 🫶

now, the situation: if a plugin stores its configuration in a data structure, updating that structure because the config file changed can be dangerous — and the reason is the asynchronous nature of plugin callbacks. 💀 like, a callback could be mid-read while you're rewriting the thing it's reading. not cute. not slay.

to dodge that entire problem, these functions let a plugin register a configuration and then later replace it with another instance without changing the instance that plugin callbacks are currently using. it works in the same manner as a shared pointer, which is exactly the energy we're going for. ✨

here's the flow, bestie:

• when a plugin needs to access the configuration data, it calls TSConfigGet() — this returns a pointer that will remain valid until the plugin calls TSConfigRelease(). 🔒
• the configuration instance is updated with TSConfigSet(), which will update an internal pointer but will not change any instance in use via TSConfigGet(). the old one just chills until everyone's done with it. 💅
• when the last in-use pointer is released, the old configuration is destructed using the function passed to func:TSConfigSet. 🗑️
• and that right there is how it handles the overlapping configuration update case correctly. no cap.

🎀 Initialization 🎀

initialization is done with TSConfigSet(). the id should be zero on the first call. this will allocate a slot for the configuration, which is returned. subsequent calls must use this value. if the id is not zero, that value is returned. 🌀

in general, the code will look something like:

class Config { ... }; // Configuration data.
int Config_Id = 0;
//...
void ConfigUpdate() {
   Config* cfg = new Config;
   cfg.load(); // load config...
   Config_Id = TSConfigSet(Config_Id, cfg,
      [](void* cfg){delete static_cast<Config*>(config);});
}
//...
PluginInit() {
   // ...
   ConfigUpdate();
   // ...
}

Config_Id is a global variable holding the configuration id, which is updated by the return value of TSConfigSet(). that's it, that's the whole trick. 🌈

⭐ Getting it back out ⭐

the configuration instance is retrieved with TSConfigGet(). this returns a wrapper class from which the configuration can be extracted with TSConfigDataGet(). the wrapper is used to release the configuration instance when it is no longer in use. 🧚

the code in a callback tends to look like:

int callback() {
   auto cfg_ref = TSConfigGet(Config_Id);
   Config* cfg = static_cast<Config*>(TSConfigDataGet(cfg_ref));
   // ... use cfg
   TSConfigRelease(Config_Id, cfg_ref);
}

see how tidy that is?? get → use → release. main character energy from start to finish. 💜

⚠️ real talk: forget the TSConfigRelease() and your old config never gets destructed. the whole shared-pointer magic only works if you actually hand the pointer back. don't leave it on read. 😭

---

💜 COPYRIGHT 💜

2026, dev@trafficserver.apache.org

---

okay and that's the whole page, bestie — this was TSCONFIG FUNCTIONS(3ts) from Apache Traffic Server, version 9.2, dated Feb 12, 2026. go forth and update your configs safely, you absolute icon. 🎀💖🦋 no more dangling config reads in your callbacks, periodt. ✨