From c31eec500832e869c046f73772c10bc096d02b24 Mon Sep 17 00:00:00 2001 From: Matthias Seitz Date: Mon, 4 Jul 2022 20:47:11 +0200 Subject: [PATCH] docs(contract): improve EventStream docs (#1450) --- ethers-contract/src/event.rs | 41 +++++++++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/ethers-contract/src/event.rs b/ethers-contract/src/event.rs index 600855a0..bc393e70 100644 --- a/ethers-contract/src/event.rs +++ b/ethers-contract/src/event.rs @@ -115,7 +115,44 @@ where M: Middleware, D: EthLogDecode, { - /// Returns a stream for the event + /// Turns this event filter into `Stream` that yields decoded events. + /// + /// This will first install a new logs filter via [`eth_newFilter`](https://docs.alchemy.com/alchemy/apis/ethereum/eth-newfilter) using the configured `filter` object. See also [`FilterWatcher`](ethers_providers::FilterWatcher). + /// + /// Once the filter is created, this will periodically call [`eth_getFilterChanges`](https://docs.alchemy.com/alchemy/apis/ethereum/eth-getfilterchanges) to get the newest logs and decode them + /// + /// **Note:** Compared to [`Self::subscribe`], which is only available on `PubsubClient`s, such + /// as Websocket, this is a poll-based subscription, as the node does not notify us when a new + /// matching log is available, instead we have to actively ask for new logs using additional RPC + /// requests, and this is done on an interval basis. + /// + /// # Example + /// + /// ``` + /// # async fn test(contract: ethers_contract::Contract) { + /// # use ethers_core::types::*; + /// # use futures_util::stream::StreamExt; + /// # use ethers_contract::{Contract, EthEvent}; + /// + /// // The event we want to get + /// #[derive(Clone, Debug, EthEvent)] + /// pub struct Approval { + /// #[ethevent(indexed)] + /// pub token_owner: Address, + /// #[ethevent(indexed)] + /// pub spender: Address, + /// pub tokens: U256, + /// } + /// + /// let ev = contract.event::().from_block(1337).to_block(2000); + /// let mut event_stream = ev.stream().await.unwrap(); + /// + /// while let Some(Ok(approval)) = event_stream.next().await { + /// let Approval{token_owner,spender,tokens} = approval; + /// } + /// + /// # } + /// ``` pub async fn stream( &'a self, ) -> Result< @@ -136,6 +173,8 @@ where D: EthLogDecode, { /// Returns a subscription for the event + /// + /// See also [Self::stream()]. pub async fn subscribe( &'a self, ) -> Result<