From ab6e6f06efc81b363635b92533549adea40c0f38 Mon Sep 17 00:00:00 2001 From: Anthony Tuininga Date: Fri, 23 Apr 2021 14:21:45 -0600 Subject: [PATCH] Documentation and sample updates for clarity and to note the fact that connection pools now always enable threading. --- doc/src/api_manual/deprecations.rst | 13 ++++++++----- doc/src/api_manual/module.rst | 13 ++++--------- doc/src/release_notes.rst | 16 ++++++++-------- doc/src/user_guide/connection_handling.rst | 11 ----------- samples/connection_pool.py | 7 +++---- samples/cqn2.py | 2 +- samples/session_callback.py | 5 ++--- samples/session_callback_plsql.py | 3 +-- 8 files changed, 27 insertions(+), 43 deletions(-) diff --git a/doc/src/api_manual/deprecations.rst b/doc/src/api_manual/deprecations.rst index cda13ed..c6ebf02 100644 --- 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 index 5bd83ca..f315e31 100644 --- 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 ` 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 index aae49c5..3e44b9e 100644 --- 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 `__). -#) 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 index e76e498..d28bb5d 100644 --- 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 `__ for an example. diff --git a/samples/connection_pool.py b/samples/connection_pool.py index 512d3e1..f7e7229 100644 --- 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 @@ import sample_env 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 index 4536364..49fe1a5 100644 --- 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 index 0964a1f..a1507fc 100644 --- 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 index 1656698..a36fc5c 100644 --- a/samples/session_callback_plsql.py +++ b/samples/session_callback_plsql.py @@ -29,8 +29,7 @@ import sample_env 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: