.\" Man page generated from reStructuredText. . .TH "TSLIFECYCLEHOOKADD" "3ts" "Mar 08, 2019" "7.1" "Apache Traffic Server" .SH NAME TSLifecycleHookAdd \- TSLifecycleHookAdd API function . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH SYNOPSIS .sp \fI#include \fP .INDENT 0.0 .TP .B void TSLifecycleHookAdd(TSLifecycleHookID\fI\ id\fP, TSCont\fI\ contp\fP) .UNINDENT .SH DESCRIPTION .sp \fI\%TSLifecycleHookAdd()\fP adds \fIcontp\fP to the list of lifecycle hooks specified by \fIid\fP\&. 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 \fBTSPluginInit()\fP (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. .SH TYPES .INDENT 0.0 .TP .B enum TSLifecycleHookID Life cycle hook selector. .INDENT 7.0 .TP .B enumerator TS_LIFECYCLE_PORTS_INITIALIZED_HOOK Called after the \fBproxy server port\fP 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 \fBtraffic_server\fP process was invoked. Other API functions that depend on server ports should be called from this hook and not \fBTSPluginInit()\fP\&. .sp Invoked with the event \fBTS_EVENT_LIFECYCLE_PORTS_INITIALIZED\fP and \fBNULL\fP data. .UNINDENT .INDENT 7.0 .TP .B 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. .sp Invoked with the event \fBTS_EVENT_LIFECYCLE_PORTS_READY\fP and \fBNULL\fP data. .UNINDENT .INDENT 7.0 .TP .B enumerator TS_LIFECYCLE_CACHE_READY_HOOK Called after Traffic Server cache initialization has finished. .sp Invoked with the event \fBTS_EVENT_LIFECYCLE_CACHE_READY\fP and \fBNULL\fP data. .UNINDENT .INDENT 7.0 .TP .B enumerator TS_LIFECYCLE_MSG_HOOK Called when triggered by an external process, such as \fBtraffic_ctl\fP\&. .sp Invoked with the event \fBTS_EVENT_LIFECYCLE_MSG\fP\&. The data is an instance of the \fI\%TSPluginMsg\fP\&. This contains a \fItag\fP 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 \fItag\fP\&. .UNINDENT .INDENT 7.0 .TP .B 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). .UNINDENT .INDENT 7.0 .TP .B 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). .UNINDENT .UNINDENT .INDENT 0.0 .TP .B TSPluginMsg The format of the data for the plugin message event \fBTS_EVENT_LIFECYCLE_MSG\fP\&. .UNINDENT .INDENT 0.0 .TP .B const char * TSPluginMsg::tag The tag of the message. This is a null terminated string. .UNINDENT .INDENT 0.0 .TP .B const void * TSPluginMsg::data Message data (payload). This is a raw slab of bytes \- no structure is guaranteed. .UNINDENT .INDENT 0.0 .TP .B size_t TSPluginMsg::data_size The size of \fI\%TSPluginMsg::data\fP\&. .UNINDENT .SH ORDERING .sp \fI\%TSLifecycleHookID::TS_LIFECYCLE_PORTS_INITIALIZED_HOOK\fP will always be called before \fI\%TSLifecycleHookID::TS_LIFECYCLE_PORTS_READY_HOOK\fP\&. .SH EXAMPLES .sp The following example demonstrates how to correctly use \fBTSNetAcceptNamedProtocol()\fP, which requires the proxy ports to be initialized and therefore does not work if called from \fBTSPluginInit()\fP directly. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #include #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)); } .ft P .fi .UNINDENT .UNINDENT .SH HISTORY .sp Lifecycle hooks were introduced to solve process initialization ordering issues (\fI\%TS\-1487\fP). 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 \fBTSPluginInit()\fP . The solution was to move \fBTSPluginInit()\fP 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. .SH SEE ALSO .sp \fBTSAPI(3ts)\fP, \fBTSContCreate(3ts)\fP .SH COPYRIGHT 2019, dev@trafficserver.apache.org .\" Generated by docutils manpage writer. .