.. Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.

.. include:: ../../common.defs

.. _developer-plugins-interfaces:

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:

.. toctree::
   :maxdepth: 2

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

.. _developer-plugins-tsfopen-family:

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:

-  :c:func:`TSfclose`

-  :c:func:`TSfflush`

-  :c:func:`TSfgets`

-  :c:func:`TSfopen`

-  :c:func:`TSfread`

-  :c:func:`TSfwrite`

Memory Allocation
=================


Traffic Server provides five routines for allocating and freeing memory.
These routines correspond to similar routines in the C library. For
example, ``TSrealloc`` behaves like the C library routine ``realloc``.

There are two main reasons for using the routines provided by Traffic
Server. The first is portability: the Traffic Server API routines behave
the same on all of Traffic Server's supported platforms. For example,
``realloc`` does not accept an argument of ``NULL`` on some platforms.
The second reason is that the Traffic Server routines actually track the
memory allocations by file and line number. This tracking is very
efficient, always turned on, and quite useful when tracking down memory
leaks.

The memory allocation functions are:

-  :c:func:`TSfree`

-  :c:func:`TSmalloc`

-  :c:func:`TSrealloc`

-  :c:func:`TSstrdup`

-  :c:func:`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
:ref:`developer-plugins-mutexes`.

The thread functions are listed below:

-  :c:func:`TSThreadCreate`
-  :c:func:`TSThreadDestroy`
-  :c:func:`TSThreadInit`
-  :c:func:`TSThreadSelf`

Debugging Functions
===================

-  :c:func:`TSDbg`
   (replaces deprecated :c:func:`TSDebug`) prints out a formatted
   statement if you are running Traffic Server in debug mode.

-  :c:func:`TSIsDbgCtlSet`
   (replaces deprecated :c:func:`TSIsDebugTagSet`)
   checks to see if a debug control (associated with a debug tag) is
   set. If the debug tag is set, then Traffic Server prints out all
   debug statements associated with the control.

-  :c:func:`TSError`
   prints error messages to Traffic Server's error log

-  :c:func:`TSAssert`
   enables the use of assertion in a plugin.

-  :c:func:`TSReleaseAssert`
   enables the use of assertion in a plugin.