- Internal oneliner apps configuration cache moved from respective

  apps objects to [a singular] snmpEngine object. That would allow
  for better cache reuse and allow for a single app working with
  many snmpEngine instances.
- Legacy interfaces and APIs dropped in new oneliner AsyncCommandGenerator
  and AsyncNotificationOriginator classes (notice 'c' in Async). Original
  AsynCommandGenerator and AsynNotificationOriginator implementations
  rebuilt on top of these new optimized versions keeping all the legacy
  for compatibility reasons. These classes no more keep references to
  SnmpEngine what makes them reusable with many SnmpEngine class instances.
- Example on a single Transport Dispatcher use with multiple SnmpEngine's
  in oneliner AsyncCommandGenerator & AsyncNotificationOriginator basaed
  applicatons added.

6 files changed, 220 insertions, 12 deletions

diff --git a/examples/v3arch/oneliner/agent/ntforg/inform-async-multiple-snmp-engines.py b/examples/v3arch/oneliner/agent/ntforg/inform-async-multiple-snmp-engines.py
new file mode 100644
index 0000000..53ddedd
--- /dev/null
+++ b/examples/v3arch/oneliner/agent/ntforg/inform-async-multiple-snmp-engines.py
@@ -0,0 +1,87 @@
+#
+# Notification Originator
+#
+# Send SNMP notifications in behalf of multiple independend SNMP engines 
+# using the following options:
+#
+# * with a single transport dispatcher and two independent SNMP engines
+# * SNMPv2c and SNMPv3
+# * with community name 'public' or USM username usr-md5-des
+# * over IPv4/UDP
+# * send IMFORM notification
+# * to multiple Managers
+# * with TRAP ID 'coldStart' specified as a MIB symbol
+# * include managed object information specified as var-bind objects pair
+#
+# Within this script we have a single asynchronous TransportDispatcher
+# and a single UDP-based transport serving two independent SNMP engines.
+# We use a single instance of AsyncNotificationOriginator with each of 
+# SNMP Engines to communicate INFORM notification to remote systems.
+#
+# When we receive a [response] message from remote system we use
+# a custom message router to choose what of the two SNMP engines
+# data packet should be handed over. The selection criteria we
+# employ here is based on peer's UDP port number. Other selection
+# criterias are also possible.
+# 
+from pysnmp.entity.rfc3413.oneliner import ntforg
+from pysnmp.entity import engine
+from pysnmp.entity.rfc3413 import context
+from pysnmp.carrier.asynsock.dispatch import AsynsockDispatcher
+from pysnmp.proto import rfc1902
+
+# List of targets in the following format:
+# ( ( authData, transportTarget ), ... )
+targets = (
+    # 1-st target (SNMPv2c over IPv4/UDP)
+    ( ntforg.CommunityData('public'),
+      ntforg.UdpTransportTarget(('localhost', 1162)) ),
+    # 2-nd target (SNMPv3 over IPv4/UDP)
+    ( ntforg.UsmUserData('usr-md5-des', 'authkey1', 'privkey1'),
+      ntforg.UdpTransportTarget(('localhost', 162)) )
+)
+
+def cbFun(sendRequestHandle, errorIndication, 
+          errorStatus, errorIndex, varBinds, cbCtx):
+    snmpEngine = cbCtx
+    if errorIndication:
+        print('Notification %s for %s not sent: %s' % (sendRequestHandle, snmpEngine.snmpEngineID.prettyPrint(), errorIndication))
+    elif errorStatus:
+        print('Notification Receiver returned error for request %s, SNMP Engine %s: %s @%s' % (sendRequestHandle, snmpEngine.snmpEngineID.prettyPrint(), errorStatus, errorIndex))
+    else:
+        print('Notification %s for SNMP Engine %s delivered:' % (sendRequestHandle, snmpEngine.snmpEngineID.prettyPrint()))
+        for name, val in varBinds:
+            print('%s = %s' % (name.prettyPrint(), val.prettyPrint()))
+
+# Instantiate the single transport dispatcher object
+transportDispatcher = AsynsockDispatcher()
+
+# Setup a custom data routing function to select snmpEngine by transportDomain
+transportDispatcher.registerRoutingCbFun(
+    lambda td,ta,d: ta[1] % 3 and 'A' or 'B'
+)
+
+snmpEngineA = engine.SnmpEngine()
+snmpEngineA.registerTransportDispatcher(transportDispatcher, 'A')
+
+snmpEngineB = engine.SnmpEngine()
+snmpEngineB.registerTransportDispatcher(transportDispatcher, 'B')
+
+ntfOrg = ntforg.AsyncNotificationOriginator()
+
+for authData, transportTarget in targets:
+    snmpEngine = transportTarget.getTransportInfo()[1][1] % 3 and \
+            snmpEngineA or snmpEngineB
+    sendPduHandle = ntfOrg.sendNotification(
+        snmpEngine,
+        context.SnmpContext(snmpEngine),
+        authData,
+        transportTarget,
+        'inform',
+        ntforg.MibVariable('SNMPv2-MIB', 'coldStart'),
+        ( ( rfc1902.ObjectName('1.3.6.1.2.1.1.1.0'),
+            rfc1902.OctetString('my name') ), ),
+        cbInfo=(cbFun, snmpEngine)
+    )
+
+transportDispatcher.runDispatcher()
diff --git a/examples/v3arch/oneliner/agent/ntforg/inform-async-multiple-transports-and-protocols.py b/examples/v3arch/oneliner/agent/ntforg/inform-async-multiple-transports-and-protocols.py
index 508f45f..095149a 100644
--- a/examples/v3arch/oneliner/agent/ntforg/inform-async-multiple-transports-and-protocols.py
+++ b/examples/v3arch/oneliner/agent/ntforg/inform-async-multiple-transports-and-protocols.py
@@ -12,6 +12,8 @@
 # * include managed object information specified as var-bind objects pair
 #
 from pysnmp.entity.rfc3413.oneliner import ntforg
+from pysnmp.entity.rfc3413 import context
+from pysnmp.entity import engine
 from pysnmp.proto import rfc1902
 
 # List of targets in the followin format:
@@ -25,8 +27,6 @@ targets = (
       ntforg.UdpTransportTarget(('localhost', 162)) )
 )
 
-ntfOrg = ntforg.AsynNotificationOriginator()
-
 def cbFun(sendRequestHandle, errorIndication, 
           errorStatus, errorIndex, varBinds, cbctx):
     if errorIndication:
@@ -39,8 +39,14 @@ def cbFun(sendRequestHandle, errorIndication,
         for name, val in varBinds:
             print('%s = %s' % (name.prettyPrint(), val.prettyPrint()))
 
+snmpEngine = engine.SnmpEngine()
+
+ntfOrg = ntforg.AsyncNotificationOriginator()
+
 for authData, transportTarget in targets:
     sendPduHandle = ntfOrg.sendNotification(
+        snmpEngine,
+        context.SnmpContext(snmpEngine),
         authData,
         transportTarget,
         'inform',
@@ -50,4 +56,4 @@ for authData, transportTarget in targets:
         cbInfo=(cbFun, None)
     )
 
-ntfOrg.snmpEngine.transportDispatcher.runDispatcher()
+snmpEngine.transportDispatcher.runDispatcher()
diff --git a/examples/v3arch/oneliner/agent/ntforg/trap-async-multiple-transports-and-protocols.py b/examples/v3arch/oneliner/agent/ntforg/trap-async-multiple-transports-and-protocols.py
index 22b74be..c8f4246 100644
--- a/examples/v3arch/oneliner/agent/ntforg/trap-async-multiple-transports-and-protocols.py
+++ b/examples/v3arch/oneliner/agent/ntforg/trap-async-multiple-transports-and-protocols.py
@@ -12,6 +12,8 @@
 # * include managed object information specified as var-bind objects pair
 #
 from pysnmp.entity.rfc3413.oneliner import ntforg
+from pysnmp.entity.rfc3413 import context
+from pysnmp.entity import engine
 from pysnmp.proto import rfc1902
 
 # List of targets in the followin format:
@@ -25,10 +27,14 @@ targets = (
       ntforg.UdpTransportTarget(('localhost', 162)) )
 )
 
-ntfOrg = ntforg.AsynNotificationOriginator()
+snmpEngine = engine.SnmpEngine()
+
+ntfOrg = ntforg.AsyncNotificationOriginator()
 
 for authData, transportTarget in targets:
     ntfOrg.sendNotification(
+        snmpEngine,
+        context.SnmpContext(snmpEngine),
         authData,
         transportTarget,
         'trap',
@@ -37,4 +43,4 @@ for authData, transportTarget in targets:
             rfc1902.OctetString('my name') ), )
     )
 
-ntfOrg.snmpEngine.transportDispatcher.runDispatcher()
+snmpEngine.transportDispatcher.runDispatcher()
diff --git a/examples/v3arch/oneliner/manager/cmdgen/get-async-multiple-snmp-engines.py b/examples/v3arch/oneliner/manager/cmdgen/get-async-multiple-snmp-engines.py
new file mode 100644
index 0000000..da9c515
--- /dev/null
+++ b/examples/v3arch/oneliner/manager/cmdgen/get-async-multiple-snmp-engines.py
@@ -0,0 +1,103 @@
+#
+# Asynchronous Command Generator
+#
+# Send SNMP GET requests using multiple independend SNMP engines 
+# with the following options:
+#
+# * with SNMPv1, community 'public' and 
+#   with SNMPv2c, community 'public' and
+#   with SNMPv3, user 'usr-md5-des', MD5 auth and DES privacy
+# * over IPv4/UDP and 
+#   over IPv6/UDP
+# * to an Agent at demo.snmplabs.com:161 and
+#   to an Agent at [::1]:161
+# * for instances of SNMPv2-MIB::sysDescr.0 and
+#   SNMPv2-MIB::sysLocation.0 MIB objects
+#
+# Within this script we have a single asynchronous TransportDispatcher
+# and a single UDP-based transport serving two independent SNMP engines.
+# We use a single instance of AsyncCommandGenerator with each of 
+# SNMP Engines to comunicate GET command request to remote systems.
+#
+# When we receive a [response] message from remote system we use
+# a custom message router to choose what of the two SNMP engines
+# data packet should be handed over. The selection criteria we
+# employ here is based on peer's UDP port number. Other selection
+# criterias are also possible.
+#
+from pysnmp.entity.rfc3413.oneliner import cmdgen
+from pysnmp.entity import engine
+from pysnmp.carrier.asynsock.dispatch import AsynsockDispatcher
+
+# List of targets in the followin format:
+# ( ( authData, transportTarget, varNames ), ... )
+targets = (
+    # 1-st target (SNMPv1 over IPv4/UDP)
+    ( cmdgen.CommunityData('public', mpModel=0),
+      cmdgen.UdpTransportTarget(('demo.snmplabs.com', 161)),
+      ( cmdgen.MibVariable('SNMPv2-MIB', 'sysDescr', 0),
+        cmdgen.MibVariable('SNMPv2-MIB', 'sysLocation', 0) ) ),
+    # 2-nd target (SNMPv2c over IPv4/UDP)
+    ( cmdgen.CommunityData('public'),
+      cmdgen.UdpTransportTarget(('demo.snmplabs.com', 1161)),
+      ( cmdgen.MibVariable('SNMPv2-MIB', 'sysDescr', 0),
+        cmdgen.MibVariable('SNMPv2-MIB', 'sysLocation', 0) ) ),
+    # 3-nd target (SNMPv3 over IPv4/UDP)
+    ( cmdgen.UsmUserData('usr-md5-des', 'authkey1', 'privkey1'),
+      cmdgen.UdpTransportTarget(('demo.snmplabs.com', 2161)),
+      ( cmdgen.MibVariable('SNMPv2-MIB', 'sysDescr', 0),
+        cmdgen.MibVariable('SNMPv2-MIB', 'sysLocation', 0) ) )
+    # N-th target
+    # ...
+)
+
+# Wait for responses or errors
+def cbFun(sendRequestHandle, errorIndication, errorStatus, errorIndex,
+          varBinds, cbCtx):
+    (snmpEngine, authData, transportTarget) = cbCtx
+    print('snmpEngine %s: %s via %s' % 
+        (snmpEngine.snmpEngineID.prettyPrint(), authData, transportTarget)
+    )
+    if errorIndication:
+        print(errorIndication)
+        return 1
+    if errorStatus:
+        print('%s at %s' % (
+            errorStatus.prettyPrint(),
+            errorIndex and varBinds[int(errorIndex)-1][0] or '?'
+            )
+        )
+        return 1
+    
+    for oid, val in varBinds:
+        if val is None:
+            print(oid.prettyPrint())
+        else:
+            print('%s = %s' % (oid.prettyPrint(), val.prettyPrint()))
+
+
+# Instantiate the single transport dispatcher object
+transportDispatcher = AsynsockDispatcher()
+
+# Setup a custom data routing function to select snmpEngine by transportDomain
+transportDispatcher.registerRoutingCbFun(
+    lambda td,ta,d: ta[1] % 3 and 'A' or 'B'
+)
+
+snmpEngineA = engine.SnmpEngine()
+snmpEngineA.registerTransportDispatcher(transportDispatcher, 'A')
+
+snmpEngineB = engine.SnmpEngine()
+snmpEngineB.registerTransportDispatcher(transportDispatcher, 'B')
+
+cmdGen = cmdgen.AsyncCommandGenerator()
+
+for authData, transportTarget, varBinds in targets:
+    snmpEngine = transportTarget.getTransportInfo()[1][1] % 3 and \
+            snmpEngineA or snmpEngineB
+    cmdGen.getCmd(
+        snmpEngine, authData, transportTarget, varBinds,
+        (cbFun, (snmpEngine, authData, transportTarget))
+    )
+
+transportDispatcher.runDispatcher()
diff --git a/examples/v3arch/oneliner/manager/cmdgen/get-async-multiple-transports-and-protocols.py b/examples/v3arch/oneliner/manager/cmdgen/get-async-multiple-transports-and-protocols.py
index 7f68d02..fab37aa 100644
--- a/examples/v3arch/oneliner/manager/cmdgen/get-async-multiple-transports-and-protocols.py
+++ b/examples/v3arch/oneliner/manager/cmdgen/get-async-multiple-transports-and-protocols.py
@@ -13,6 +13,7 @@
 # * for instances of SNMPv2-MIB::sysDescr.0 and
 #   SNMPv2-MIB::sysLocation.0 MIB objects
 #
+from pysnmp.entity import engine
 from pysnmp.entity.rfc3413.oneliner import cmdgen
 
 # List of targets in the followin format:
@@ -70,15 +71,17 @@ def cbFun(sendRequestHandle, errorIndication, errorStatus, errorIndex,
         else:
             print('%s = %s' % (oid.prettyPrint(), val.prettyPrint()))
 
-cmdGen  = cmdgen.AsynCommandGenerator()
+snmpEngine = engine.SnmpEngine()
+
+cmdGen  = cmdgen.AsyncCommandGenerator()
 
 # Submit GET requests
 for authData, transportTarget, varNames in targets:
     cmdGen.getCmd(
-        authData, transportTarget, varNames,
+        snmpEngine, authData, transportTarget, varNames,
         # User-space callback function and its context
         (cbFun, (authData, transportTarget)),
         lookupNames=True, lookupValues=True
     )
 
-cmdGen.snmpEngine.transportDispatcher.runDispatcher()
+snmpEngine.transportDispatcher.runDispatcher()
diff --git a/examples/v3arch/oneliner/manager/cmdgen/getnext-async-multiple-transports-and-protocols.py b/examples/v3arch/oneliner/manager/cmdgen/getnext-async-multiple-transports-and-protocols.py
index 76b860f..73ce642 100644
--- a/examples/v3arch/oneliner/manager/cmdgen/getnext-async-multiple-transports-and-protocols.py
+++ b/examples/v3arch/oneliner/manager/cmdgen/getnext-async-multiple-transports-and-protocols.py
@@ -12,6 +12,7 @@
 #   to an Agent at [::1]:161
 # * for multiple MIB subtrees and tables
 #
+from pysnmp.entity import engine
 from pysnmp.entity.rfc3413.oneliner import cmdgen
 
 # List of targets in the followin format:
@@ -71,16 +72,18 @@ def cbFun(sendRequestHandle, errorIndication, errorStatus, errorIndex,
 
     return True # continue table retrieval
 
-cmdGen  = cmdgen.AsynCommandGenerator()
+snmpEngine = engine.SnmpEngine()
+
+cmdGen  = cmdgen.AsyncCommandGenerator()
 
 # Submit initial GETNEXT requests and wait for responses
 for authData, transportTarget, varNames in targets:
-    varBindHead = [ x[0] for x in cmdGen.makeReadVarBinds(varNames) ]
+    varBindHead = cmdGen.makeVarBindsHead(snmpEngine, varNames)
     cmdGen.nextCmd(
-        authData, transportTarget, varNames,
+        snmpEngine, authData, transportTarget, varNames,
         # User-space callback function and its context
         (cbFun, (varBindHead, authData, transportTarget)),
         lookupNames=True, lookupValues=True
     )
 
-cmdGen.snmpEngine.transportDispatcher.runDispatcher()
+snmpEngine.transportDispatcher.runDispatcher()