Document how to re-use connections

[jgeewax]

From a customer:

All of the docs seem to create one client per query. Most projects which use datastore will want some form of concurrency. The docs don’t provide any guidance or support for connection pooling, or what is inexpensive v.s expensive, e.g. what actually involves RPC. From my reading of logs, it looked like the first call to fetch makes an HTTP call to auth, and later calls are just an RPC. Unclear if there is any connection re-use, or the best practice from a performance perspective.

Ideally we have some standard pattern where you create a client and perhaps import that client from elsewhere, reusing it for queries?

[tseaver]

@jgeewax Right now, we don't support sharing a client between threads. See #926, #1214, #1346. #2160 talks about making it easier to copy a client for use in a new thread. Clients are just lightweight wrappers around their connection objects, which means that keeping a separate instance per thread is quite workable.

I don't know that there is anything datastore-specific about the issue.

[theacodes]

Discussion about making our HTTP library (and this connections) thread safe is over at #1346. Closing this issue.