api: WaitForUpdatesEx & DestroyPropertyFilter

[akutz]

Description

This patch introduces Ex variants for many of the property collector types/methods to take advantage of the remote API DestroyPropertyFilter. Now it is possible to use a single property collector for waiting for updates and remove previously added filters.

BREAKING: The semantics around the helper functions in the
          property package have changed. Please review any
          code that calls this package to ensure it is
          compatible with the new behaviors.

Closes: NA

Type of change

Please mark options that are relevant:

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update
• Build related change

How Has This Been Tested?

• New unit test for property.WaitForUpdatesEx
• New unit test for property.Collector's WaitForUpdatesEx function
• New unit test for DestroyPropertyFilter

Checklist:

• My code follows the CONTRIBUTION guidelines of this project
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged

[dougm]

Thanks @akutz
The new property.WaitForUpdatesEx lgtm.
Keep in mind ServiceContent.PropertyCollector (aka property.DefaultCollector()) is a session singleton, not safe for multiple threads to WaitForUpdatesEx on.
object.Task.{Wait,WaitForResult} and the new Ex versions both use DefaultCollector.Create(), so the Ex version(s) are not thread safe.
Thinking:

• leave the existing object.Task methods as-is
• change task.Wait to always use property.WaitForUpdatesEx, rather than add task.WaitEx (don't think anyone currently calls task.Wait directly?)
• then apps would call task.Wait to re-use a PC instance

property.Filter - tempted to do a breaking rename of the existing type, to property.Match or ?
Then property.Filter can be used to wrap the MO instead of FilterEx

[akutz]

Hi @dougm ,

Thanks for taking a look. Yeah, the concurrency thing is an issue. What are your thoughts on starting WaitForUpdatesEx in a Goroutine the moment a session is established, using the default PC, and then we change the way Wait occurs for everybody else to:

• Register on update callback
• Add prop filter
• Receive update via callback
• Remove prop filter

That way there's always a single, long-running WaitForUpdates goroutine that can be used to listen for all updates, whenever there's a prop filter added?

[akutz]

Hey @dougm,

Please see the refactored PR. I added a lock to the PropertyCollector such that any calls to WaitForUpdates, WaitForUpdatesEx, or CheckForUpdates must obtain an exclusive lock on the property collector. The attempt to obtain the lock will timeout if the context is cancelled.

[dougm]

Thanks @akutz , can you also add a BREAKING: section to the commit? Suggesting one more for the list (CreateFilter)

[dougm]

lgtm, thanks @akutz !