Skip to content

Document that JRuby task counts are approximate - #1125

Open
0z5a wants to merge 1 commit into
ruby-concurrency:masterfrom
0z5a:document-jruby-task-counts
Open

0z5a wants to merge 1 commit into
ruby-concurrency:masterfrom
0z5a:document-jruby-task-counts

Conversation

@0z5a

@0z5a 0z5a commented Nov 19, 2026

Copy link
Copy Markdown

Fixes #1121.

I started from #1121 and checked it against the code. On JRuby, JavaThreadPoolExecutor#scheduled_task_count and #completed_task_count return Java's ThreadPoolExecutor#getTaskCount and #getCompletedTaskCount, which the Java docs call approximate. RubyThreadPoolExecutor increments its own counters under its lock when a task is posted and when it finishes, so on CRuby the counts are exact. The docs of both methods don't mention the difference.

This PR takes the docs option from the issue. It adds a note to the thread_pool_executor_attr_reader_scheduled_task_count and thread_pool_executor_attr_reader_completed_task_count macros in fixed_thread_pool.rb. These macros are used by both executors and by the attribute list of ThreadPoolExecutor, so the note shows up there and on the pools that inherit from it. The note says that on JRuby a task that was just posted can be missing from both counts, so the two can be equal before that task has run. JavaThreadPoolExecutor itself is @!visibility private, so I did not put the note there.

The other option from the issue, counting posted and finished tasks in JavaThreadPoolExecutor as RubyThreadPoolExecutor does, changes the post path and has to agree with the Ruby executor on rejected and caller-run tasks. I left that choice to you.

How I found it

I followed scheduled_task_count and completed_task_count from the ThreadPoolExecutor docs to both implementations and compared them. Then I ran the script from the issue against concurrent-ruby 1.3.8:

  • JRuby 10.0.2.0 (jruby-complete, Temurin 21): 727/1000 and 911/1000 posted tasks were missing from both counts in two runs.
  • CRuby 4.0.7, with lib/ from master: 0/1000.

Where this can show up in practice

Code that waits for a pool to become idle by checking completed_task_count == scheduled_task_count, for example in test helpers. On JRuby that check can pass while a task that was just posted is still pending, as the issue describes for the Action Cable tests in Rails. With the note, the docs no longer suggest that the two counts are exact on every platform. This is my estimate beyond the report in #1121.

Testing

  • yard doc --markup markdown on lib/concurrent-ruby/**/*.rb: the new text appears in the scheduled_task_count and completed_task_count entries of Concurrent::ThreadPoolExecutor.
  • ruby -c on the changed file.
  • Not run: bundle exec rake and the specs (comment-only change), and rake yard with the project template.

On JRuby, scheduled_task_count and completed_task_count come from
Java's ThreadPoolExecutor#getTaskCount and #getCompletedTaskCount,
which Java documents as approximate. A task handed to an idle worker
that has not started it yet is in neither count, so the two can be
equal while that task is still pending. RubyThreadPoolExecutor counts
a task when it is posted, so the counts are exact there.

Say this in the shared macros, which are used for ThreadPoolExecutor
and the pools built on it.

Fixes ruby-concurrency#1121

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Task counts can miss a just-posted task on JRuby

1 participant