NAME¶
TSLifecycleHookAdd -
SYNOPSIS¶
#include <ts/ts.h>
- void TSLifecycleHookAdd(TSLifecycleHookID id,
TSCont contp)
DESCRIPTION¶
TSLifecycleHookAdd() adds
contp to the list of lifecycle hooks
specified by
id. Lifecycle hooks are based on the Traffic Server
process, not on any specific transaction or session. These will typically be
called only once during the execution of the Traffic Server process and
therefore should be added in
TSPluginInit() (which could itself be
considered a lifecyle hook). Unlike other hooks, lifecycle hooks may not have
a well defined ordering and use of them should not assume that one of the
hooks is always called before another unless specifically mentioned.
- TS_LIFECYCLE_PORTS_INITIALIZED_HOOK
- Called after the proxy server port data structures have been
initialized but before connections are accepted on those ports. The
sockets corresponding to the ports may or may not be open depending on how
the traffic_server process was invoked. Other API functions that
depend on server ports should be called from this hook and not
TSPluginInit().
Invoked with the event TS_EVENT_LIFECYCLE_PORTS_INITIALIZED and
NULL data.
- TS_LIFECYCLE_PORTS_READY_HOOK
- Called after enabling connections on the proxy server ports. Because
Traffic Server is threaded this may or may not be called before any
connections are accepted. The hook code may assume that any connection to
Traffic Server started after this hook is called will be accepted by
Traffic Server, making this a convenient place to signal external
processes of that.
Invoked with the event TS_EVENT_LIFECYCLE_PORTS_READY and NULL
data.
- TS_LIFECYCLE_CACHE_READY_HOOK
- Called after Traffic Server cache initialization has finished.
Invoked with the event TS_EVENT_LIFECYCLE_CACHE_READY and NULL
data.
- TS_LIFECYCLE_MSG_HOOK
- Called when triggered by an external process, such as traffic_ctl.
Invoked with the event TS_EVENT_LIFECYCLE_MSG. The data is an
instance of the TSPluginMsg. This contains a tag which is a
null terminated string and a data payload. The payload cannot be assumed
to be null terminated and is created by the external agent.
ORDERING¶
TS_LIFECYCLE_PORTS_INITIALIZED_HOOK will always be called before
TS_LIFECYCLE_PORTS_READY_HOOK.
EXAMPLES¶
The following example demonstrates how to correctly use
TSNetAcceptNamedProtocol(), which requires the proxy ports to be
initialized and therefore does not work if called from
TSPluginInit()
directly.
#include <ts/ts.h>
#define SSL_PROTOCOL_NAME "whatever"
static int
ssl_proto_handler(TSCont contp, TSEvent event, void* data)
{
/// Do named protocol handling.
}
static int
local_ssl_init(TSCont contp, TSEvent event, void * edata)
{
if (TS_EVENT_LIFECYCLE_PORTS_INITIALIZED == event) { // just to be safe.
TSNetAcceptNamedProtocol(
TSContCreate(ssl_proto_handler, TSMutexCreate()),
SSL_PROTOCOL_NAME
);
}
return 0;
}
void
TSPluginInit (int argc, const char * argv[])
{
TSLifecycleHookAdd(TS_LIFECYCLE_PORTS_INITIALIZED_HOOK, TSContCreate(local_ssl_init, NULL));
}
HISTORY¶
Lifecycle hooks were introduced to solve process initialization ordering issues
TS-1487. Different API calls required different modules of Traffic
Server to be initialized for the call to work, but others did not work that
late in initialization, which was problematic because all of them could
effectively only be called from
TSPluginInit() . The solution was to
move
TSPluginInit() as early as possible in the process initialization
and provide hooks for API calls that needed to be invoked later which served
essentially as additional pluging initialization points.
SEE ALSO¶
TSAPI(3ts),
TSContCreate(3ts)
COPYRIGHT¶
2015, dev@trafficserver.apache.org