Is httpx.Client thread safe?

[pfmoore]

I'm writing a multi-threaded application that makes HTTP requests. The way I have my code structured, I'd like to share a single httpx.Client instance between my worker threads. Is that possible? I've looked through the docs, and I can't see any information on thread safety.

I could probably structure my code to use a client per worker (or maybe I'd need to do one per connection if I can't work out how to add setup code to concurrent.futures workers), but as I'm fetching a load of files from a single server, sharing a client seems like it would be better for performance.

Just for completeness, I'll note that I can't use async, because one of my classes needs a sync interface.

[lovelydinosaur]

Yes. HTTPX is intended to be thread-safe, and yes, a single client-instance across all threads will do better in terms of connection pooling, than using an instance-per-thread.

We might want to figure a good place in the docs to write about this. (?)

I've not looked through requests or urllib3 to see where they choose to discuss this in their own docs. Their docs choices here might be a useful pointer for us.

(And thank you for the clearly framed question, much appreciated 💚)

[pfmoore]

Thanks for the quick reply! For what it's worth, requests doesn't say much - from a search, an older version of the docs seems to have had "Thread safe" in the features list but it's missing from the latest version...

If it helps, the two places I looked where I would have hoped to find something were:

• The Client class documentation. If the summary said "An HTTP client, with connection pooling, HTTP/2, redirects, cookie persistence, etc. Can be shared between threads." that would have been sufficient for me.
• For more detailed information, I looked in the "Advanced Usage" section for a "Thread Safety" section. That might be overkill if all there is to say is "yes, it should be fine" though 🙂

[ralokt]

As someone who read up on httpx for unrelated reasons, and is now considering switching over from requests in part because of thread safety would also be nice to have, the first place I hoped to see it was in the list of features on the introduction page. Just a bullet point there that links to this discussion should make it very visible already, I think. If you want to specify that concurrent requests are safe, but closing a client that is being used by other threads isn't, probably a page makes sense? I'd probably expect that under "Advanced", maybe "Advanced -> Thread Safety"?

[lovelydinosaur]

and is now considering switching over from requests in part because of thread safety

requests and urllib3 are also thread safe.

the first place I hoped to see it was in the list of features on the introduction page.

I'm not sure. We do need to balance informing our users without overwhelming them with info. Perhaps it should simply be included as one of the bullet points?

The underlying httpcore networking component is more specific here.

[ralokt]

Sorry for taking a while to reply to this!

requests and urllib3 are also thread safe.

Do we know that?
I tried to find out, and found this stackoverflow question that links to these issues:

• Our use of urllib3's ConnectionPools is not threadsafe. psf/requests#1871
• Document threading contract for Session class psf/requests#2766

To me, that's not conclusive. Of course, if the issues that existed came from urllib3, then that being thread-safe SHOULD mean that requests is, too, assuming that that was previously the only cause for it not to be - but also, there is no positive verification of this, and there is a report of a race condition when closing connections in the first linked issue.

the first place I hoped to see it was in the list of features on the introduction page.

I'm not sure. We do need to balance informing our users without overwhelming them with info. Perhaps it should simply be included as one of the bullet points?

That's what I meant! List as in, the HTML list :)

The underlying httpcore networking component is more specific here.

That's great, but also, hard to find. I wouldn't have thought to go through the dependencies and read their documentation to get that information - especially as just because httpx builds on httpcore doesn't mean that it can't introduce its own race conditions. So positive affirmation of that would be nice - doesn't have to be long, just state that httpx is itself written in a thread-safe way and builds on httpcore, which is also thread-safe.

I understand that you're the author of both (btw, thanks for that!), so it probably feels redundant - but, as an outside perspective, I only just realized that (and that httpcore even exists) as I was writing this comment.

As a library user looking to use httpx in a multi-threaded context, this would maybe be the single most valuable part of the documentation - it means an assurance that what I build won't break in a (specific but common) way that can't be easily or properly fixed. I'm not exaggerating. If the rest of the documentation were just the source code, but I knew that thread safety wasn't an issue, I would happily take a bit of slow progress over risking debugging a race condition in something I've released via bug reports from users.

[erdnaxeli]

Hi, is the same true with the async interface? Can I use the same (async) client in concurrent tasks?

[lovelydinosaur]

Yes. HTTPX is thread and task safe. Looks like we oughta be highlighting that in the docs.

[lee-cq]

For AyncClient, it is thread-safe, but it is worth noting that the connection pool cannot be shared among multiple Event Loops.

So if you use the same asynchronous client in multiple Event Loops, you may need to disable connection pooling, otherwise you will encounter some problems (eg. #2959).

[lovelydinosaur]

if you use the same asynchronous client in multiple Event Loops, you may need to disable connection pooling

That's not quite the correct synopsis here, no.
Rephrase that to "don't use an asynchronous client in multiple Event Loops".

(It will typically just error if you do, but it'd be neater if we outright prevented it.)

[steve-mavens]

For what it's worth, this is currently the top hit on Google for "httpx thread safety", which arguably is worth as much as finding the right place for it in the docs!

[cosven]

I doubt that there are race conditions in Client code

Think about this case

1. thread A calls Client.send method and it stops at L888
2. thread B calls Client.close method and it stops at L1257
3. thread A continues to run and it turns client.state to OPENED

In this case, thread A tries to send a request on an already-closed client.

Client.close method

httpx/httpx/_client.py

Lines 1251 to 1261 in 87f39f1

	def close(self) -> None:
	"""
	Close transport and proxies.
	"""
	if self._state != ClientState.CLOSED:
	self._state = ClientState.CLOSED
	self._transport.close()
	for transport in self._mounts.values():
	if transport is not None:
	transport.close()

Client.send method

httpx/httpx/_client.py

Lines 888 to 892 in 87f39f1

	"""
	if self._state == ClientState.CLOSED:
	raise RuntimeError("Cannot send a request, as the client has been closed.")
	self._state = ClientState.OPENED

[lovelydinosaur]

Muhuh. Yeah you probs can close the client like that, with the not-very-terrible outcome that the transport will raise an exception indicating that it's been closed.

We could have threading locks around the close/open state, but I'd prefer we don't. (Or rather I'd prefer we don't at this layer. We do at the transport layer.) Adding those would be overkill.

[cosven]

Or rather I'd prefer we don't at this layer. We do at the transport layer.

From another perspective, can we say that it is not very good to maintain the open/close state on the Client level.

[karpetrosyan]

By saying httpx is thread-safe and task-safe, we should understand that we can do as many requests as we want concurrently, and it's not going to break the client state, which is true.

Closing the client in one thread and making requests in another would probably break the client state, as you mentioned.
Although this is not really how httpx is used, we can discuss handling such cases in httpx.

In most cases, you simply create a client instance locally or globally, make concurrent requests, and then close it.