Undocumented behavior of `local_work_bucket`

[qinsoon]

Currently for GCWorker, there are two kinds of local work.

mmtk-core/src/scheduler/worker.rs

Line 57 in e027342

local_work_buffer: Vec<(WorkBucketStage, Box<dyn GCWork<VM>>)>,

local_work_buffer is the locally cached work. It only contains work from activated work buckets (work from inactivated bucket will be pushed to the global bucket instead). Work in the buffer can be pushed to the global bucket when the buffer exceeds its limit. If any work stays in the local_work_buffer, it is prioritized before local_work_bucket and any work polled from global buckets.

mmtk-core/src/scheduler/worker.rs

Line 23 in e027342

pub local_work_bucket: WorkBucket<VM>,

This is mostly used to dispatch per-GCWorker packet, as it can be accessed by the scheduler. We use it to schedule per-worker packet for PrepareCollector and ReleaseCollector. However, the timing of executing work in local_work_bucket is unreliable.

1. Work in local_work_bucket is only scheduled when a worker tries to pull from global (i.e. it exhausted local_work_bucket first). This means if a work packet keeps adding work to its local_work_buffer, there might be a long delay before we execute work in local_work_bucket.
2. Work in local_work_bucket does not prevent new bucket being activated. So it is possible that when a work packet is pushed to local_work_bucket during bucket A, the work might be actually executed in subsequent bucket B, C, D... There is no guarantee about when the work will be executed. The only guarantee is that the work will be executed by the worker before the worker can execute any other global work.

This is not a bug, but I feel we should improve the documentation to make it more clear.

[qinsoon]

This can be closed. #507 solved this issue: local_work_bucket is renamed to designated_work, and work in this bucket will be executed before the scheduler can open any new bucket.