From dafe381e07f410e1eccbf6268fff950825686479 Mon Sep 17 00:00:00 2001
From: Rainer Gerhards <rgerhards@adiscon.com>
Date: Wed, 6 Nov 2013 12:55:36 +0100
Subject: doc: document output plugin calling interface changes

---
 doc/v8compatibility.html | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/doc/v8compatibility.html b/doc/v8compatibility.html
index 4aa9be41..72bab322 100644
--- a/doc/v8compatibility.html
+++ b/doc/v8compatibility.html
@@ -25,6 +25,44 @@ action.writeAllMarkMessages="off" to the actions in question.
 changed. It is suggested to review some of the project-provided plugins for
 full details. In this doc, we describe the most important changes from a high
 level perspective.
+<p><b>Multi-thread awareness required</b></p>
+<p>The new engine activates one <b>worker</b>instance of output actions on 
+each worker thread. This means an action has now three types of data:
+<ul>
+<li>global
+<li>action-instance - previously known pData, one for each action inside the config
+<li>worker-action-instance - one for each worker thread (called pWrkrData), note
+that this is specific to exactly one pData
+</ul>
+The plugin <b>must</b> now by multi-threading aware. It may be called by multiple
+threads concurrently, but it is guaranteed that each call is for a unique
+pWrkrData structure. This still permits to write plugins easily, but enables the
+engine to work with much higher performance. Note that plugin developers
+should assume it is the norm that multiple concurrent worker action instances
+are active a the some time.
+
+<p><b>New required entry points</b></p>
+<p>In order to support the new threading model, new entry points are required.
+Most importantly, only the plugin knows which data must be present in pData and
+pWrkrData, so it must created and destroy these data structures on request of
+the engine. Note that pWrkrData may be destroyed at any time and new ones
+re-created later. Depending on workload structure and configuration, this can happen
+frequently.
+<p>New entry points are:
+<ul>
+<li>createWrkrInstance
+<li>freeWrkrInstance
+</ul>
+
+The calling interface for these entry points has changed. Basically,
+they now receive a pWrkrData object instead pData. It is assumed that
+createWrkrInstance populates pWrkrData->pData appropriately.
+<ul>
+<li>beginTransaction
+<li>doAction
+<li>endTransaction
+</ul>
+
 <p><b>RS_RET_SUSPENDED is no longer supported when creating an action instance</b>
 <p>This means a plugin must not try to establish any connections or the like
 before any of its processing entry points (like beginTransaction or doAction)
@@ -32,7 +70,6 @@ is called. This was generally also the case von v7, but was not enforced in
 all cases. In v8, creating action creation fails if anything but RS_RET_OK
 is returned.
 
-
 <a href="http://www.rsyslog.com/g/BSD">rsyslog BSD blocks info</a>
 page for more information and how to upgrade your config.
 <p>[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
-- 
cgit v1.2.3