Plugin Interfaces

Most of the functions in the Traffic Server API provide an interface to specific code modules within Traffic Server. The miscellaneous functions described in this chapter provide some useful general capabilities. They are categorized as follows:

The C library already provides functions such as printf, malloc, and fopen to perform these tasks. The Traffic Server API versions, however, overcome various C library limitations (such as portability to all Traffic Server-support platforms).

TSfopen Family

The fopen family of functions in C is normally used for reading configuration files, since fgets is an easy way to parse files on a line-by-line basis. The TSfopen family of functions aims at solving the same problem of buffered IO and line at a time IO in a platform-independent manner. The fopen family of C library functions can only open a file if a file descriptor less than 256 is available. Since Traffic Server often has more than 2000 file descriptors open at once, however, the likelihood of an available file descriptor less than 256 very small. To solve this problem, the TSfopen family can open files with descriptors greater than 256.

The TSfopen family of routines is not intended for high speed IO or flexibility - they are blocking APIs (not asynchronous). For performance reasons, you should not directly use these APIs on a Traffic Server thread (when being called back on an HTTP hook); it is better to use a separate thread for doing the blocking IO. The TSfopen family is intended for reading and writing configuration information when corresponding usage of the fopen family of functions is inappropriate due to file descriptor and portability limitations. The TSfopen family of functions consists of the following:

• TSfclose()

• TSfflush()

• TSfgets()

• TSfopen()

• TSfread()

• TSfwrite()

メモリー割り当て

Traffic Server はメモリーの割り当てと解放のための5つのルーチンを提供しています。これらのルーチンは C ライブラリの同様のルーチンと一致します。例えば、TSrealloc は C ライブラリルーチンの realloc のように振る舞います。

Traffic Server が提供するルーチンを使用する主な理由は二つあります。一つ目は移植性です。Traffic Server API ルーチンは Traffic Server がサポートするプラットフォームすべてにおいて同じ振る舞いをします。例えば、いくつかのプラットフォームでは realloc が NULL の引数を受け付けません。二つ目の理由は Traffic Server ルーチンが実はメモリー割り当てをファイルと行番号で追跡していることです。この追跡はとても効率的で、常に有効化されており、メモリーリークを探し出すときになかなか便利です。

メモリー割り当て関数には以下のものがあります。

• TSfree()

• TSmalloc()

• TSrealloc()

• TSstrdup()

• TSstrndup()

Thread Functions

The Traffic Server API thread functions enable you to create, destroy, and identify threads within Traffic Server. Multithreading enables a single program to have more than one stream of execution and to process more than one transaction at a time. Threads serialize their access to shared resources and data using the TSMutex type, as described in Mutexes.

The thread functions are listed below:

• TSThreadCreate()

• TSThreadDestroy()

• TSThreadInit()

• TSThreadSelf()

Debugging Functions

• TSDebug() prints out a formatted statement if you are running Traffic Server in debug mode.

• TSIsDebugTagSet() checks to see if a debug tag is set. If the debug tag is set, then Traffic Server prints out all debug statements associated with the tag.

• TSError() prints error messages to Traffic Server's error log

• TSAssert() enables the use of assertion in a plugin.

• TSReleaseAssert() enables the use of assertion in a plugin.