NAME

       TSLifecycleHookAdd - TSLifecycleHookAdd API function

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 lifecycle 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.

TYPES

       enum TSLifecycleHookID
              Life cycle hook selector.

              enumerator 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.

              enumerator 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.

              enumerator 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.

              enumerator 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. Its internal
                     structure and format are  entirely  under  the  control  of  the  external  agent  although
                     presumably  there  is  an  agreement  between  the  plugin  and  the external where this is
                     determined by the tag.

              enumerator TS_LIFECYCLE_CLIENT_SSL_CTX_INITIALIZED_HOOK
                     Called after the initialization of the SSL context used  by  Traffic  Server  for  outbound
                     connections (Traffic Server as client).

              enumerator TS_LIFECYCLE_SERVER_SSL_CTX_INITIALIZED_HOOK
                     Called  after  every  SSL  context  initialization  used  by  Traffic  Server  for  inbound
                     connections (Traffic Server as the server).

              enumerator TS_LIFECYCLE_TASK_THREADS_READY_HOOK
                     Called after Traffic Server task threads have been started.

                     Invoked with the event TS_EVENT_LIFECYCLE_TASK_THREADS_READY and NULL data.

              enumerator TS_LIFECYCLE_SHUTDOWN_HOOK
                     Called after Traffic Server receiving a shutdown signal, such as SIGTERM.

                     Invoked with the event TS_EVENT_LIFECYCLE_SHUTDOWN and NULL data.

       struct TSPluginMsg
              The data for the plugin message event TS_EVENT_LIFECYCLE_MSG.

              const char *tag
                     The tag of the message. This is a null terminated string.

              const void *data
                     Message data (payload). This is a raw slab of bytes - no structure is guaranteed.

              size_t data_size
                     The number of valid bytes pointed at by TSPluginMsg.data.

ORDERING

       TSLifecycleHookID::TS_LIFECYCLE_PORTS_INITIALIZED_HOOK     will     always     be      called      before
       TSLifecycleHookID::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 plugin initialization points.

SEE ALSO

       TSAPI(3ts), TSContCreate(3ts)

COPYRIGHT

       2025, dev@trafficserver.apache.org

9.2                                               Mar 17, 2025                           TSLIFECYCLEHOOKADD(3ts)