TSLifecycleHookAdd

概要

#include <ts/ts.h>

void TSLifecycleHookAdd(TSLifecycleHookID id, TSCont contp)

解説

TSLifecycleHookAdd() は contp を id で指定されるライフサイクルフックのリストに追加します。ライフサイクルフックは特定のトランザクションやセッションではなく Traffic Server プロセスのもとに成り立ちます。これらは一般的に Traffic Server プロセスの実行中に一度だけ呼び出されるので、( それ自体もライフサイクルフックとみなされる ) TSPluginInit() の中で追加されるべきです。他のフックと違い、ライフサイクルフックは明確な順序を持たず、使用にあたっては特に言及されていない限りフックのうちの一つが常に他のどれかより前に呼び出されると仮定すべきではありません。

Types

enum TSLifecycleHookID

Life cycle hook selector.

enumerator TS_LIFECYCLE_PORTS_INITIALIZED_HOOK

プロキシーサーバーポート データ構造が初期化された後、接続がそれらのポート上で accept される前に呼ばれます。ポートに対応するソケットは traffic_server プロセスがどのように起動されたかによって open されることもされないこともあります。サーバーポートに依存するその他の API 関数は TSPluginInit() ではなくこのフックから呼ばれるべきです。

Invoked with the event TS_EVENT_LIFECYCLE_PORTS_INITIALIZED and nullptr 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 nullptr 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 nullptr 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 nullptr data.

enumerator TS_LIFECYCLE_SSL_SECRET_HOOK

Called before the data for the certificate or key is loaded. The data argument to the callback is a pointer to a TSSecretID which contains a pointer to the name of the certificate or key and the relevant version if applicable.

This hook gives the plugin a chance to load the certificate or key from an alternative source and set via the TSSslSecretSet() API. If there is no plugin override, the certificate or key will be loaded from disk and the secret name will be interpreted as a file path.

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

順番

TSLifecycleHookID::TS_LIFECYCLE_PORTS_INITIALIZED_HOOK will always be called before TSLifecycleHookID::TS_LIFECYCLE_PORTS_READY_HOOK.

例

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, nullptr));
}

歴史

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)