diff --git a/README.rst b/README.rst index b9acc3edc..f526f2727 100644 --- a/README.rst +++ b/README.rst @@ -307,6 +307,21 @@ Processing each frame in a framed message involves a certain amount of overhead. increasing the frame size can offer potentially significant performance gains. We recommend that you tune these values to your use-case in order to obtain peak performance. +Thread safety +========================== +The ``EncryptionSDKClient`` and all provided ``CryptoMaterialsManager`` are thread safe. +But instances of ``BaseKMSMasterKeyProvider`` MUST not be shared between threads, +for the reasons outlined in `the boto3 docs `_. + +Because the ``BaseKMSMaterKeyProvider`` creates a `new boto3 sessions `_ per region, +users do not need to create a client for every region in every thread; +a new ``BaseKMSMasterKeyProvider`` per thread is sufficient. + +(The ``BaseKMSMasterKeyProvider`` is the internal parent class of all the KMS Providers.) + +Finally, while the ``CryptoMaterialsCache`` is thread safe, +sharing entries in that cache across threads needs to be done carefully +(see the !Note about partition name `in the API Docs `_). .. _AWS Encryption SDK: https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/introduction.html .. _cryptography: https://cryptography.io/en/latest/