get_queue_length and get_thread_count not well documented

[biddisco]

During my cleanup of scheduling code (shared_priority_scheduler) I have been worried by the uses of
get_queue_length and get_thread_count as they are not well documented and it is not completely clear what the difference between the 2 should be (c.f. #1868 ) and when one or the other should be used.

My understanding is that get_queue_length simply reports the number of tasks in the pending/staged queues (regardless of state/priority), whereas get_thread_count (which accepts state/priority flags) does a more specific query and can include suspended threads that are not in the queues (and must be found from the thread_map).

I would like a clear definition of what these functions should count so that I can a) improve the documentation, and b) ensure that the code changes I am making are counting the right things.

[biddisco]

I will try to make this easier to respond to be asking specifically whether my interpretation is correct

get_queue_length(priority) should return the number of staged+pending tasks in a given queue. When priority is requested, this should be either high/low/normal and return the length of the appropriate queues. If priority is unknown or undefined, then the sum of all high/low/normal queues should be returned.
When called on the scheduler::get_queue_length(id, priority), it should return the number for the queue/thread id requested. if the id is -1 then it returns the total for all queues/threads.

get_thread_count(state, priority) returns terminated_items_count for the terminated state and for staged/pending counts it returns the subset of get_queue_length() above (which is the sum of both staged and pending). For the suspended state, it must traverse the thread map and count them. If state is unknown then we return the total of map - staged - terminated - which gives essentially the ones that are ??? - what should it return?

[hkaiser]

@biddisco your interpretation sounds about right. Thanks for this clarification.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale]

This issue has been automatically closed. Please re-open if necessary.