.\" Man page generated from reStructuredText.
.
.
.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
..
.TH "TSCONTCALL" "3ts" "Nov 02, 2023" "9.2" "Apache Traffic Server"
.SH NAME
TSContCall \- TSContCall API function
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
#include <ts/ts.h>
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B int  TSContCall(\fI\%TSCont\fP  contp, \fI\%TSEvent\fP  event, void  *edata) 
.UNINDENT
.SH DESCRIPTION
.sp
Call the continuation \fIcontp\fP as if from a hook with the event type \fIevent\fP and data of
\fIedata\fP\&. Presuming \fIcontp\fP was created in a manner like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
TSContCreate(CallbackHandler, TSMutexCreate());
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Therefore there is a function:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
int CallbackHandler(TSCont this, TSEvent id, void * data);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As a result \fI\%TSContCall()\fP will effectively do:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
return CallbackHandler(contp, event, edata);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If there is a mutex associated with \fIcontp\fP, \fI\%TSContCall()\fP assumes that mutex is held already.
\fI\%TSContCall()\fP will directly call the handler associated with the continuation.  It will return the
value returned by the handler in \fIcontp\fP\&.
.sp
If \fIcontp\fP has a mutex, the plugin must acquire the lock on the mutex for \fIcontp\fP before calling
\fI\%TSContCall()\fP\&. See \fI\%TSContMutexGet()\fP and \fI\%TSMutexLockTry()\fP for mechanisms for doing this.
.sp
The most common case is the code called by \fI\%TSContCall()\fP must complete before further code is executed
at the call site. An alternative approach to handling the locking directly would be to split the call site
into two continuations, one of which is signalled (possibly via \fI\%TSContCall()\fP) from the original
\fI\%TSContCall()\fP target.
.sp
Note mutexes returned by \fI\%TSMutexCreate()\fP are recursive mutexes, therefore if the lock is
already held on the thread of execution acquiring the lock again is very fast. Mutexes are also
shareable so that the same mutex can be used for multiple continuations.:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
TSMutex mutex = TSMutexCreate();
TSCont cont1 = TSContCreate(Handler1, mutex);
TSCont cont2 = TSContCreate(Handler2, mutex);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this example case, \fBcont1\fP can assume the lock for \fBcont2\fP is held. This should be
considered carefully because for the same reason any thread protection between the continuations is
removed. This works well for tightly coupled continuations that always operate in a fixed sequence.
.SH COPYRIGHT
2023, dev@trafficserver.apache.org
.\" Generated by docutils manpage writer.
.