Using the Driver in Multithreaded Applications

Asynchronous APIs

Our asynchronous API is designed to be used in SwiftNIO-based applications running atop EventLoopGroups composed of one or more EventLoops.

You must pass in your application’s EventLoopGroup when initializing a MongoClient, like:

let client = try MongoClient("mongodb://localhost:27017", using: myEventLoopGroup)

We strongly recommend using a single, global MongoClient per application. Each client is backed by a pool of connections per each server in the in MongoDB deployment, and utilizes a background thread to continuously monitor the state of the MongoDB deployment. Using a single client allows these resources to be efficiently shared throughout your application.

The following types are all designed to be safe to access across multiple threads/Tasks/EventLoops:

We make no guarantees about the safety of using any other type across threads.

Special Considerations when using `EventLoopFuture` APIs

This section is only relevant if you are working with EventLoopFutures. If you are using structured concurrency and async/await APIs, you do not need to worry about these considerations.

Although the types listed above are thread-safe, by default each will not necessarily always return EventLoopFutures on the same EventLoop you are using them on. Each time an EventLoopFuture is generated, they will call EventLoopGroup.next() on the MongoClient‘s underyling EventLoopGroup to select a next EventLoop to use.

To ensure thread safety when working with these returned futures, you should call hop(to:) on them in order to “hop” the future over to your current event loop, which ensures any callbacks you register on the future will fire on your current event loop.

Depending on your use case, a more convenient alternative for you may be to use versions of these core driver types which are “bound” to particular EventLoops, i.e. that always automatically return EventLoopFutures on the EventLoop they are bound to (as opposed to any EventLoop from the underlying EventLoopGroup).

To use the “bound” API, you can call bound(to:) on your global MongoClient to instantiate an EventLoopBoundMongoClient, which a small wrapper type around a MongoClient that returns futures solely on its bound EventLoop. Any child MongoDatabases or MongoCollections retrieved from the bound client will automatically be bound to the same EventLoop as the client.

Please see the EventLoopFuture documentation for more details on multithreading.

Usage With Server-side Swift Frameworks

See the Examples/ directory in the driver GitHub repository for examples of how to integrate the driver in multithreaded frameworks.

Sync API

In the synchronous API, we strongly recommend using a single, global MongoClient per application. Each client is backed by a pool of connections per each server in the in MongoDB deployment, and utilizes a background thread to continuously monitor the state of the MongoDB deployment. Using a single client allows these resources to be efficiently shared throughout your application.