Please document when `HashMap::insert_async` can wait

[joshtriplett]

It's not entirely clear under what circumstances HashMap::insert_async will wait. Is it possible for insert_async to have to wait, if a reader currently has a reference to an item in the same bucket in which HashMap wants to do the insert?

Details: I'm considering a design that has a table of OnceCell values, which get created when kicking off a network request for a set of resources, and initialized when the request comes back. I want to make sure that tasks blocking on a OnceCell don't block the insertion of new OnceCells.

[wvwwvwwv]

Yes, your understanding is correct. => I'll update the doc.

Not sure if I understood the usage correctly, but I don't think it's a good design to hold a reference to an OnceCell when making network requests, since entries sharing the same bucket won't be accessible to others while doing so.

In order to minimise false sharing, I would consider initialising HashMap with a large capacity. Or, if blocking others is not at all an option, consider HashMap<K, Arc<OnceCell>> then passing Arc<OnceCell> around network calls; this involves more heap memory allocations, but holding Arc<OnceCell> wouldn't block other threads.

[joshtriplett]

I appreciate the update; now that I know the circumstances under which insert operations can block, I'll go with a different design.