Documentation and sample updates for clarity and to note the fact that

anthony-tuininga · anthony-tuininga · commit ab6e6f06efc8 · 2021-04-23T14:21:45.000-06:00
connection pools now always enable threading.
diff --git a/doc/src/api_manual/deprecations.rst b/doc/src/api_manual/deprecations.rst
@@ -18,7 +18,8 @@ if applicable. The most recent deprecations are listed first.
       - Comments
     * - `encoding` parameter to :meth:`cx_Oracle.connect()`
       - No longer needed as the use of encodings other than UTF-8 is
-        deprecated.
+        deprecated. Encoding is handled internally between cx_Oracle and Oracle
+        Database.
     * - `nencoding` parameter to :meth:`cx_Oracle.connect()`
       - No longer needed as the use of encodings other than UTF-8 is
         deprecated.
@@ -30,13 +31,15 @@ if applicable. The most recent deprecations are listed first.
         deprecated.
     * - Connection.maxBytesPerCharacter
       - No longer needed as the use of encodings other than UTF-8 is
-        deprecated.
-    * - positional parmeters to :meth:`cx_Oracle.connect()`
+        deprecated. The constant value 4 can be used instead.
+    * - Positional parameters to :meth:`cx_Oracle.connect()`
       - Replace with keyword parameters in order to comply with the Python
         database API.
-    * - positional parmeters to :meth:`cx_Oracle.SessionPool()`
+    * - positional parameters to :meth:`cx_Oracle.SessionPool()`
       - Replace with keyword parameters in order to comply with the Python
         database API.
+    * - `threaded` parameter to :meth:`cx_Oracle.SessionPool()`
+      - The value of this parameter is ignored. Threading is now always used.
     * - `waitTimeout` parameter to :meth:`cx_Oracle.SessionPool()`
       - Replace with parameter name `wait_timeout`
     * - `maxLifetimeSession` parameter to :meth:`cx_Oracle.SessionPool()`
@@ -46,7 +49,7 @@ if applicable. The most recent deprecations are listed first.
     * - `maxSessionsPerShard` parameter to :meth:`cx_Oracle.SessionPool()`
       - Replace with parameter name `max_sessions_per_shard`
     * - `payloadType` parameter to :meth:`Connection.queue()`
-      - Replace with parameter name `payload_type` if using keyword parmeters.
+      - Replace with parameter name `payload_type` if using keyword parameters.
     * - `ipAddress` parameter to :meth:`Connection.subscribe()`
       - Replace with parameter name `ip_address`
     * - `groupingClass` parameter to :meth:`Connection.subscribe()`
diff --git a/doc/src/api_manual/module.rst b/doc/src/api_manual/module.rst
@@ -78,8 +78,7 @@ Module Interface
 
     The threaded parameter is expected to be a boolean expression which
     indicates whether or not Oracle should wrap accesses to connections with a
-    mutex. Doing so in single threaded applications imposes a performance
-    penalty of about 10-15% which is why the default is False.
+    mutex.
 
     The events parameter is expected to be a boolean expression which indicates
     whether or not to initialize Oracle in events mode. This is required for
@@ -250,11 +249,6 @@ Module Interface
     :meth:`~SessionPool.acquire()` will create connection objects of that type,
     rather than the base type defined at the module level.
 
-    The threaded parameter is expected to be a boolean expression which
-    indicates whether Oracle should wrap accesses to connections with a mutex.
-    Doing so in single threaded applications imposes a performance penalty of
-    about 10-15% which is why the default is False.
-
     The getmode parameter indicates whether or not future
     :func:`SessionPool.acquire()` calls will wait for available connections.  It
     can be one of the :ref:`Session Pool Get Modes <sesspoolmodes>` values.
@@ -352,7 +346,8 @@ Module Interface
         parameter `sessionCallback` was renamed to `session_callback` and the
         parameter `maxSessionsPerShard` was renamed to
         `max_sessions_per_shard`. The old names will continue to work as
-        keyword parameters for a period of time.
+        keyword parameters for a period of time. The `threaded` parameter value
+        is ignored and threading is always enabled.
 
 
 .. function:: Time(hour, minute, second)
@@ -429,7 +424,7 @@ General
 
     Note that in order to make use of multiple threads in a program which
     intends to connect and disconnect in different threads, the threaded
-    parameter to :meth:`connect()` or :meth:`SessionPool()` must be true.
+    parameter to :meth:`connect()` must be `True`.
 
 
 .. data:: version
diff --git a/doc/src/release_notes.rst b/doc/src/release_notes.rst
@@ -15,7 +15,7 @@ Version 8.2 (TBD)
     pools. This significantly improves the performance of methods
     :meth:`SodaDatabase.createCollection()` (when not specifying a value for
     the metadata parameter) and :meth:`SodaDatabase.openCollection()`. Caching
-    is available when using Oracle Client version 19.11 and higher
+    is available when using Oracle Client version 19.11 and higher.
 #)  Added support for supplying hints to SODA operations. A new non-terminal
     method :meth:`~SodaOperation.hint()` was added and a `hint` parameter was
     added to the methods :meth:`SodaCollection.insertOneAndGet()`,
@@ -26,20 +26,20 @@ Version 8.2 (TBD)
     :meth:`cx_Oracle.SessionPool()` in order to permit specifying the size of
     the statement cache during the creation of pools and standalone
     connections.
+#)  Threaded mode is now always enabled when creating connection pools with
+    :meth:`cx_Oracle.SessionPool()`. Any `threaded` parameter value is ignored.
 #)  Eliminated a memory leak when calling :meth:`SodaOperation.filter()` with a
     dictionary.
 #)  The distributed transaction handle assosciated with the connection is now
     cleared on commit or rollback (`issue 530
     <https://github.com/oracle/python-cx_Oracle/issues/530>`__).
-#)  Stop passing unsupported flags to dpiSodaDocCursor_getNext().
 #)  Added check to ensure that when setting variables or object attributes, the
     type of the temporary LOB must match the expected type.
-#)  In order to follow the PEP 8 naming style a number of parameter names,
-    method names and attribute names were modified. The old names will be
-    removed in a subsequent release of cx_Oracle. In addition, the use of
-    encodings other than UTF-8 is also deprecated. See
-    :ref:`_deprecations_8_2` for details.
-#)  Improved test suite.
+#)  A small number of parameter, method, and attribute names were updated to
+    follow the PEP 8 style guide. This brings better consistency to the
+    cx_Oracle API. The old names are still usable but may be removed in a
+    future release of cx_Oracle. See :ref:`_deprecations_8_2` for details.
+#)  Improved the test suite.
 
 
 Version 8.1 (December 2020)
diff --git a/doc/src/user_guide/connection_handling.rst b/doc/src/user_guide/connection_handling.rst
@@ -316,17 +316,6 @@ for a connection to become available if all are currently in use, for example:
     pool = cx_Oracle.SessionPool("hr", userpwd, "dbhost.example.com/orclpdb1",
                   min=2, max=5, increment=1, getmode=cx_Oracle.SPOOL_ATTRVAL_WAIT, encoding="UTF-8")
 
-
-Applications that are using connections concurrently in multiple threads should
-set the ``threaded`` parameter to *True* when creating a connection pool:
-
-.. code-block:: python
-
-    # Create the session pool
-    pool = cx_Oracle.SessionPool("hr", userpwd, "dbhost.example.com/orclpdb1",
-                  min=2, max=5, increment=1, threaded=True, encoding="UTF-8")
-
-
 See `ConnectionPool.py
 <https://github.com/oracle/python-cx_Oracle/tree/master/samples/ConnectionPool.py>`__
 for an example.
diff --git a/samples/connection_pool.py b/samples/connection_pool.py
@@ -12,9 +12,8 @@
 # The script uses threading to show multiple users of the pool. One thread
 # performs a database sleep while another performs a query. A more typical
 # application might be a web service that handles requests from multiple users.
-# Applications that use connections concurrently in multiple threads should set
-# the 'threaded' parameter to True. Note only one operation (such as an execute
-# or fetch) can take place at a time on each connection.
+# Note only one operation (such as an execute or fetch) can take place at a time
+# on each connection.
 #
 # Also see session_callback.py.
 #
@@ -29,7 +28,7 @@
 pool = oracledb.SessionPool(user=sample_env.get_main_user(),
                             password=sample_env.get_main_password(),
                             dsn=sample_env.get_connect_string(), min=2,
-                            max=5, increment=1, threaded=True)
+                            max=5, increment=1)
 
 def the_long_query():
     with pool.acquire() as conn:
diff --git a/samples/cqn2.py b/samples/cqn2.py
@@ -61,7 +61,7 @@ def callback(message):
 pool = oracledb.SessionPool(user=sample_env.get_main_user(),
                             password=sample_env.get_main_password(),
                             dsn=sample_env.get_connect_string(), min=2, max=5,
-                            increment=1, events=True, threaded=True)
+                            increment=1, events=True)
 with pool.acquire() as connection:
     qos = oracledb.SUBSCR_QOS_QUERY | oracledb.SUBSCR_QOS_ROWIDS
     sub = connection.subscribe(callback=callback, timeout=1800, qos=qos)
diff --git a/samples/session_callback.py b/samples/session_callback.py
@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2019, 2020, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2019, 2021, Oracle and/or its affiliates. All rights reserved.
 #------------------------------------------------------------------------------
 
 #------------------------------------------------------------------------------
@@ -81,8 +81,7 @@ def init_session(conn, requested_tag):
 pool = oracledb.SessionPool(user=sample_env.get_main_user(),
                             password=sample_env.get_main_password(),
                             dsn=sample_env.get_connect_string(), min=2, max=5,
-                            increment=1, threaded=True,
-                            session_callback=init_session)
+                            increment=1, session_callback=init_session)
 
 # acquire session without specifying a tag; since the session returned is
 # newly created, the callback will be invoked but since there is no tag
diff --git a/samples/session_callback_plsql.py b/samples/session_callback_plsql.py
@@ -29,8 +29,7 @@
 pool = oracledb.SessionPool(user=sample_env.get_main_user(),
                             password=sample_env.get_main_password(),
                             dsn=sample_env.get_connect_string(), min=2, max=5,
-                            increment=1, threaded=True,
-                            session_callback="pkg_SessionCallback.TheCallback")
+                            increment=1, session_callback="pkg_SessionCallback.TheCallback")
 
 # truncate table logging calls to PL/SQL session callback
 with pool.acquire() as conn:
