Skip to content

[pigeon] Clarify event channel usage on the Dart side #177776

Description

@stuartmorgan-g

See #177723 for context; regardless of whether we provide extra wrappers, the discussion there highlights that the current API is unclear:

  • There's no documentation on the generated method indicating how to use it.
  • The naming doesn't indicate that this is creating a new object that owns the channels (unlike the raw EventChannel API, where you explicitly create the event channel, then ask that for a stream)

That makes it easy to use incorrectly. We should:

  • Definitely add docs to the generated code, indicated both that it shouldn't be called multiple times for the same instance, and that the returned stream is a broadcast stream.
  • Consider adding an intermediate event channel object wrapping the EventChannel, so that usage feels more like the method channel, or
  • if not, strongly consider renaming it so it doesn't sound like a simple getter. E.g., instead of a Pigeon-defined event channel method Type foo() just creating a method Stream<Type> foo(...), it could be something like Stream<Type> createFooStream(...)

While we are making a breaking change, it looks like if a Pigeon file had two different EventChannelApi declarations with streams with the same name it would probably generated code that collides, so however we address this we should make sure that case works as part of the design.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Important issues not at the top of the work listp: pigeonrelated to pigeon messaging codegen toolpackageflutter/packages repository. See also p: labels.team-ecosystemOwned by Ecosystem teamtriaged-ecosystemTriaged by Ecosystem team

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions