Overview documentation for worker_pool and worker_pool_worker

2 files changed, 22 insertions, 5 deletions

diff --git a/src/worker_pool.erl b/src/worker_pool.erl
index 608cea9166..06a670ff4c 100644
--- a/src/worker_pool.erl
+++ b/src/worker_pool.erl
@@ -18,13 +18,25 @@
 
 %% Generic worker pool manager.
 %%
-%% Supports nested submission of jobs (nested jobs always run
-%% immediately in current worker process).
+%% Submitted jobs are functions. They can be executed asynchronously
+%% (using worker_pool:submit/1, worker_pool:submit/2) or synchronously
+%% (using worker_pool:submit_async/1).
 %%
-%% Possible future enhancements:
+%% Supports nested submission of jobs and two execution modes:
+%% 'single' and 'reuse'. Jobs executed in 'single' mode are invoked in
+%% a one-off process. Those executed in 'reuse' mode are invoked in a
+%% worker process out of the pool. Nested jobs are always executed
+%% immediately in current worker process.
 %%
-%% 1. Allow priorities (basically, change the pending queue to a
-%% priority_queue).
+%% Caller submissions are enqueued internally. When the next worker
+%% process is available, it communicates it to the pool and is
+%% assigned a job to execute. If job execution fails with an error, no
+%% response is returned to the caller.
+%%
+%% Worker processes prioritise certain command-and-control messages
+%% from the pool.
+%%
+%% Future improvement points: job prioritisation.
 
 -behaviour(gen_server2).
 
diff --git a/src/worker_pool_worker.erl b/src/worker_pool_worker.erl
index 819a6ae8ce..c2d058923d 100644
--- a/src/worker_pool_worker.erl
+++ b/src/worker_pool_worker.erl
@@ -16,6 +16,11 @@
 
 -module(worker_pool_worker).
 
+%% Executes jobs (functions) submitted to a worker pool with worker_pool:submit/1,
+%% worker_pool:submit/2 or worker_pool:submit_async/1.
+%%
+%% See worker_pool for an overview.
+
 -behaviour(gen_server2).
 
 -export([start_link/0, next_job_from/2, submit/3, submit_async/2, run/1]).