From b321559a22a3ee6490695ecb9d95d3c9fbf7ee1c Mon Sep 17 00:00:00 2001 From: Thiago Macieira Date: Mon, 29 Apr 2019 11:13:04 -0700 Subject: [PATCH] Document OOM conditions in the QArrayData-based containers The other containers probably don't handle as well, so I just documented the ones that I know how they work. Fixes: QTBUG-75470 Change-Id: I95ecabe2f50e450c991afffd159a0483aac35a79 Reviewed-by: Allan Sandfeld Jensen Reviewed-by: Albert Astals Cid Reviewed-by: Thiago Macieira --- src/corelib/tools/qbytearray.cpp | 17 +++++++++++++++++ src/corelib/tools/qstring.cpp | 18 ++++++++++++++++++ src/corelib/tools/qvector.qdoc | 18 ++++++++++++++++++ 3 files changed, 53 insertions(+) diff --git a/src/corelib/tools/qbytearray.cpp b/src/corelib/tools/qbytearray.cpp index 6cc41a8956..c2c2b9de28 100644 --- a/src/corelib/tools/qbytearray.cpp +++ b/src/corelib/tools/qbytearray.cpp @@ -1043,6 +1043,23 @@ QByteArray qUncompress(const uchar* data, int nbytes) and QByteArray() compares equal to QByteArray(""). We recommend that you always use isEmpty() and avoid isNull(). + \section1 Maximum size and out-of-memory conditions + + The current version of QByteArray is limited to just under 2 GB (2^31 + bytes) in size. The exact value is architecture-dependent, since it depends + on the overhead required for managing the data block, but is no more than + 32 bytes. Raw data blocks are also limited by the use of \c int type in the + current version to 2 GB minus 1 byte. + + In case memory allocation fails, QByteArray will throw a \c std::bad_alloc + exception. Out of memory conditions in the Qt containers are the only case + where Qt will throw exceptions. + + Note that the operating system may impose further limits on applications + holding a lot of allocated memory, especially large, contiguous blocks. + Such considerations, the configuration of such behavior or any mitigation + are outside the scope of the QByteArray API. + \section1 Notes on Locale \section2 Number-String Conversions diff --git a/src/corelib/tools/qstring.cpp b/src/corelib/tools/qstring.cpp index ee9d486eb8..a0e33d4e45 100644 --- a/src/corelib/tools/qstring.cpp +++ b/src/corelib/tools/qstring.cpp @@ -1777,6 +1777,24 @@ const QString::Null QString::null = { }; and the \c{'+'} will automatically be performed as the \c{QStringBuilder} \c{'%'} everywhere. + \section1 Maximum size and out-of-memory conditions + + The current version of QString is limited to just under 2 GB (2^31 bytes) + in size. The exact value is architecture-dependent, since it depends on the + overhead required for managing the data block, but is no more than 32 + bytes. Raw data blocks are also limited by the use of \c int type in the + current version to 2 GB minus 1 byte. Since QString uses two bytes per + character, that translates to just under 2^30 characters in one QString. + + In case memory allocation fails, QString will throw a \c std::bad_alloc + exception. Out of memory conditions in the Qt containers are the only case + where Qt will throw exceptions. + + Note that the operating system may impose further limits on applications + holding a lot of allocated memory, especially large, contiguous blocks. + Such considerations, the configuration of such behavior or any mitigation + are outside the scope of the Qt API. + \sa fromRawData(), QChar, QLatin1String, QByteArray, QStringRef */ diff --git a/src/corelib/tools/qvector.qdoc b/src/corelib/tools/qvector.qdoc index 75b17a4207..ad5821e73b 100644 --- a/src/corelib/tools/qvector.qdoc +++ b/src/corelib/tools/qvector.qdoc @@ -173,6 +173,24 @@ For a detailed discussion comparing Qt containers with each other and with STL containers, see \l {Understand the Qt Containers}. + \section1 Maximum size and out-of-memory conditions + + The current version of QVector is limited to just under 2 GB (2^31 bytes) + in size. The exact value is architecture-dependent, since it depends on the + overhead required for managing the data block, but is no more than 32 + bytes. The number of elements that can be stored in a QVector is that size + divided by the size of each element. + + In case memory allocation fails, QVector will use the \l Q_CHECK_PTR macro, + which will throw a \c std::bad_alloc exception if the application is being + compiled with exception support. If exceptions are disabled, then running + out of memory is undefined behavior. + + Note that the operating system may impose further limits on applications + holding a lot of allocated memory, especially large, contiguous blocks. + Such considerations, the configuration of such behavior or any mitigation + are outside the scope of the Qt API. + \sa QVectorIterator, QMutableVectorIterator, QList, QLinkedList */