Lwt: Lwt_pool docs are misleading

[fxfactorial]

My use case is that I have say 10 dedicated Lwt created servers and each server provides the same service, albeit on different ports. For handling the response for the server's callback, I thought a good thing to use would be Lwt_pool. So that in the sever's call back I'd have: Lwt_pool.use some_pool (fun _ -> ... This way I could lessen the time in getting an Lwt.t and just get straight to work of the request. I don't actually have anything useful to give the worker thread, so I am just passing unit.

Unfortunately after talking on IRC to def and others, it seems that Lwt_pool is not at all about having a pool of resources for which you pull in, grab one, and give back to the pool when you're done (as is every other programming environment's meaning of pool), rather its about limiting concurrency and that makes it sound more like a semaphore than a pool.

Clarification appreciated and especially appreciated if docs were clearer. Also no pool destroy function?

[aantron]

Thank you. Relevant discussion: http://irclog.whitequark.org/ocaml/2016-05-17#16483274;

[hcarty]

For what it's worth, Lwt_pool does act as I would have expected - it managed a pool of resources (ex. database connections) which can be pulled from while limiting the overall number of instances of that resource.

The interface has limitations, like the lack of clear, delete or filter (see #183) functions for managing a pool over time. But for the seemingly intended use case it does work well.

[fxfactorial]

It should be clearer that the resources being pooled are the 'a of a Lwt.t in the pool, not the Lwt.t threads themselves.

[hcarty]

That's fair. I had always assumed that it was the 'a being pooled based on the signature of use:

val use : 'a t -> ('a -> 'b Lwt.t) -> 'b Lwt.t

but a few extra words would make this explicit.

[aantron]

Nonetheless, I think the documentation could be improved with better word choice in several places, and potentially a brief example, to better and quicker focus the reader's mind on what Lwt_pool actually does, instead of preconceptions about what "pools" do in other libraries or languages the reader may have experience with.

[aantron]

@fxfactorial Mind glancing at the above commit?

[fxfactorial]

Perfect!