diff --git a/specification.json b/specification.json index 937273aa..505644cf 100644 --- a/specification.json +++ b/specification.json @@ -230,7 +230,7 @@ { "id": "Requirement 1.6.1", "machine_id": "requirement_1_6_1", - "content": "The API MUST define a `shutdown` function which, when called, must call the respective `shutdown` function on the active provider.", + "content": "The API MUST define a mechanism to propagate a shutdown request to active providers.", "RFC 2119 keyword": "MUST", "children": [] }, @@ -386,7 +386,7 @@ { "id": "Requirement 2.5.1", "machine_id": "requirement_2_5_1", - "content": "The provider MAY define a `shutdown` function to perform whatever cleanup is necessary for the implementation.", + "content": "The provider MAY define a mechanism to gracefully shutdown and dispose of resources.", "RFC 2119 keyword": "MAY", "children": [] }, diff --git a/specification/sections/01-flag-evaluation.md b/specification/sections/01-flag-evaluation.md index 8b592207..5e5a3492 100644 --- a/specification/sections/01-flag-evaluation.md +++ b/specification/sections/01-flag-evaluation.md @@ -39,15 +39,18 @@ See [provider](./02-providers.md) for details. > The `provider mutator` function **MUST** invoke the `initialize` function on the newly registered provider before using it to resolve flag values. +Application authors can await the newly set `provider's` readiness using the `PROVIDER_READY` event. +Provider instances which are already active (because they have been bound to other `names` or otherwise) need not be initialized again. The `provider's` readiness can state can be determined from its `status` member/accessor. -See [provider initialization](./02-providers.md#24-initialization). +See [event handlers and initialization](./05-events.md#event-handlers-and-initialization), [provider initialization](./02-providers.md#24-initialization). #### Requirement 1.1.2.3 > The `provider mutator` function **MUST** invoke the `shutdown` function on the previously registered provider once it's no longer being used to resolve flag values. -Setting a new provider means the previous provider is no longer in use, and should therefore be disposed of using its `shutdown` function. +When a provider is no longer in use, it should be disposed of using its `shutdown` mechanism. +Provider instances which are bound to multiple names won't be shut down until the last binding is removed. see: [shutdown](./02-providers.md#25-shutdown), [setting a provider](#setting-a-provider) @@ -274,9 +277,9 @@ See [hooks](./04-hooks.md) for details. #### Requirement 1.6.1 -> The API **MUST** define a `shutdown` function which, when called, must call the respective `shutdown` function on the active provider. +> The API **MUST** define a mechanism to propagate a shutdown request to active providers. -The precise name of this function is not prescribed by this specification, but should be defined be the SDK. -Relevant language idioms should be considered when choosing the name for this function, in accordance with the resource-disposal semantics of the language in question. +The global API object might expose a `shutdown` function, which will call the respective `shutdown` function on the registered providers. +Alternatively, implementations might leverage language idioms such as auto-disposable interfaces or some means of cancellation signal propagation to allow for graceful shutdown. see: [`shutdown`](./02-providers.md#25-shutdown) diff --git a/specification/sections/02-providers.md b/specification/sections/02-providers.md index da562118..08f75620 100644 --- a/specification/sections/02-providers.md +++ b/specification/sections/02-providers.md @@ -236,7 +236,8 @@ see: [error codes](https://openfeature.dev/specification/types#error-code) #### Requirement 2.5.1 -> The provider **MAY** define a `shutdown` function to perform whatever cleanup is necessary for the implementation. +> The provider **MAY** define a mechanism to gracefully shutdown and dispose of resources. + ```java // MyProvider implementation of the dispose function defined in Provider class MyProvider implements Provider, AutoDisposable { @@ -249,6 +250,5 @@ class MyProvider implements Provider, AutoDisposable { ``` Providers may maintain remote connections, timers, threads or other constructs that need to be appropriately disposed of. -Provider authors may implement the `shutdown` function to perform relevant clean-up actions. -The precise name of this function is not prescribed by this specification, but should be defined be the SDK. -Relevant language idioms should be considered when choosing the name for this function, in accordance with the resource-disposal semantics of the language in question. \ No newline at end of file +Provider authors may implement a `shutdown` function to perform relevant clean-up actions. +Alternatively, implementations might leverage language idioms such as auto-disposable interfaces or some means of cancellation signal propagation to allow for graceful shutdown. \ No newline at end of file