Use case

Many plugins allow creating multiple instances of a platform class or resource (e.g. multiple instances of a video player, audio player, etc.) with each maintaining its own state. Currently pigeon allows creating only a single instance of an API, and this forces an instance ID to be passed as an extra parameter on all API calls. This also requires the platform implementation of every method to do a lookup on that ID. The issue with this is more noticeable on plugins that implement a large number of methods, method channels and event channels per instance, but a solution to this problem would benefit plugins on any scale.

In my plugin, I solve this problem by creating separate instances of method channels and event channels for each API instance. It would be useful to support this same solution in pigeon not only because it would be more convenient and more efficient but also because it would allow authors of federated plugins to implement the platform interface in their preferred way right from the beginning. This is important since federated plugins cannot introduce breaking platform interface changes, they must get it right from the beginning.

Proposal

Allow a method in an API to return an API. For example:

@HostApi()
abstract class VideoPlayerPluginApi {
  void initialize();
  // This is how the proposed new feature would be introduced:
  VideoPlayerApi create(CreateMessage msg);
}

@HostApi()
abstract class VideoPlayerApi {
  // Note it is no longer necessary to pass the instance id to each of these methods
  void dispose();
  void setLooping(LoopingMessage msg);
  void setVolume(VolumeMessage msg);
  void play();
  PositionMessage position();
  void seekTo(PositionMessage msg);
  void pause();
  void setMixWithOthers(MixWithOthersMessage msg);
}

When a new instance is created, pigeon can generate a unique instance ID and add it as a suffix to the method channel name. (It "might" also be necessary to add more annotation data to to let it know that VideoPlayerPluginApi.create creates an instance.)

Future versions of pigeon could also allow configuring the method channel name / pattern via the annotation to help plugin developers to maintain backward compatibility in their platform interface.

I have mentioned above that different instances of an API should also be able to maintain different instances event channels. I have submitted a separate proposal to add support for event channels (#66711).

@gaaclarke