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

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

       TSPluginMsg
              The format of the data for the plugin message event TS_EVENT_LIFECYCLE_MSG.

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

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

       size_t TSPluginMsg::data_size
              The size of 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
       pluging initialization points.

SEE ALSO

       TSAPI(3ts), TSContCreate(3ts)

COPYRIGHT

       2018, dev@trafficserver.apache.org