[fix][broker] Run ResourceGroup tasks only when tenants/namespaces registered

[vinkal-chudgar]

Motivation

Fixes #24693.

ResourceGroupService unconditionally schedules two periodic tasks (aggregating local usage and calculating quotas) during broker initialization, executing them every resourceUsageTransportPublishIntervalInSecs (default 60 seconds) regardless of whether any tenants or namespaces are registered to resource groups. This wastes resources on brokers where the resource group feature is unused.

This PR implements explicit lifecycle management: periodic tasks now start only when the first tenant or namespace is registered to any resource group, and stop when the last registration is removed. This eliminates unnecessary periodic task execution and resource consumption on brokers where the resource group feature is idle.

Modifications

• Lazy scheduling: Periodic tasks (aggregateResourceGroupLocalUsages, calculateQuotaForAllResourceGroups) are no longer unconditionally started in initialize(). They start only when tenant or namespace registrations are added (via registerTenant/registerNameSpace calls) and stop when the last registration is removed.
• Automatic cleanup: Tasks stop automatically when the last attachment is removed, eliminating background work when resource groups become unused.
• CAS-guarded concurrency: Task lifecycle is controlled via an AtomicBoolean with compare-and-set to avoid double start/stop and blocking.
• Dynamic config: Existing dynamic rescheduling based on resourceUsageTransportPublishIntervalInSecs is preserved; guards prevent reschedule attempts when schedulers are stopped.
• Docs: Updated the ServiceConfiguration field doc to reflect “run only when in use” and to clarify behavior when a ResourceUsageTransportManager is configured.

Modified files

• ResourceGroupService.java: add maybeStartSchedulers(), maybeStopSchedulersIfIdle(), hasActiveAttachments(), plus small guard/logging improvements.
• ServiceConfiguration.java: clarify resourceUsageTransportPublishIntervalInSecs doc.
• ResourceGroupServiceTest.java: add new tests and adapt existing tests for lazy lifecycle.

Verifying this change

• Make sure that the change passes the CI checks.

This change is verified by unit tests. Tests are sleep free, run with per test isolation, and use 60s timeouts.

New unit tests (ResourceGroupServiceTest.java)

• testLazyStartStopAndReschedule() verifies lazy start, deterministic reschedule on interval change, and stop on last detach.
• testNoStartOnRGCreateOnly() ensures no schedulers start when a resource group has no attachments and direct calls do not auto start.
• testStartOnTenantAttachment() confirms that a tenant only attachment starts both schedulers and detaching the last tenant stops them.
• testStopOnLastDetachWithMixedRefs() checks that schedulers keep running while any attachment exists and stop only after the last is removed.
• testNoRescheduleWhenStopped() ensures interval changes do not schedule tasks when the service is idle.

Updated unit tests (ResourceGroupServiceTest.java)

• testClose(): start schedulers via an attachment, call close(), then assert scheduled task references are set to null and isSchedulersRunning() is false.

• testResourceGroupOps(): The test now calls calculateQuotaForAllResourceGroups() before unregistering all attachments, rather than after.

Test utilities

• isSchedulersRunning() accessor annotated with com.google.common.annotations.VisibleForTesting.
• createResourceGroupService() helper that returns a fresh ResourceGroupService(pulsar) per test.

Personal CI Results

Tested in Personal CI fork: vinkal-chudgar#1

Status:

• 43 checks passed (build, tests, validation)
• 3 coverage upload jobs failed due to missing Codecov token (expected in forks)
• All core test suites passed successfully

Evidence: https://github.com/vinkal-chudgar/pulsar/pull/1/checks

Does this pull request potentially affect one of the following parts:

If the box was checked, please highlight the changes

• Dependencies (add or upgrade a dependency)
• The public API
• The schema
• The default values of configurations
• The threading model
• The binary protocol
• The REST endpoints
• The admin CLI options
• The metrics
• Anything that affects deployment

Configuration note: Only the documentation string for resourceUsageTransportPublishIntervalInSecs was updated. No default values were changed.

Documentation

• doc
• doc-required
• doc-not-needed
• doc-complete

Note: Inline configuration documentation was updated in ServiceConfiguration.java. No website docs need changes

Matching PR in forked repository

PR in forked repository: vinkal-chudgar#1

[github-actions]

@vinkal-chudgar Please add the following content to your PR description and select a checkbox:

- [ ] `doc` <!-- Your PR contains doc changes -->
- [ ] `doc-required` <!-- Your PR changes impact docs and you will update later -->
- [ ] `doc-not-needed` <!-- Your PR changes do not impact docs -->
- [ ] `doc-complete` <!-- Docs have been already added -->

[lhotari]

Thanks for the great contribution! I didn't do a full review yet. A few minor comments.

[vinkal-chudgar]

Thanks for the great contribution! I didn't do a full review yet. A few minor comments.

Thanks for the quick look! I'll address the comments when available.

[vinkal-chudgar]

@lhotari - When convenient, could you please review this PR?

[lhotari]

Would it make sense to have a method hasActiveResourceGroups() for avoiding duplication of the logic?

[lhotari]

Is "attachment" an existing concept? Just wondering if a resource group could be considered "active" when it has at least one usage? Therefore the name could be hasActiveResourceGroups etc ?