docs(contract): improve EventStream docs (#1450)

This commit is contained in:
Matthias Seitz 2022-07-04 20:47:11 +02:00 committed by GitHub
parent b232afaabc
commit c31eec5008
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 40 additions and 1 deletions

View File

@ -115,7 +115,44 @@ where
M: Middleware, M: Middleware,
D: EthLogDecode, 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<M:ethers_providers::Middleware>(contract: ethers_contract::Contract<M>) {
/// # 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::<Approval>().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( pub async fn stream(
&'a self, &'a self,
) -> Result< ) -> Result<
@ -136,6 +173,8 @@ where
D: EthLogDecode, D: EthLogDecode,
{ {
/// Returns a subscription for the event /// Returns a subscription for the event
///
/// See also [Self::stream()].
pub async fn subscribe( pub async fn subscribe(
&'a self, &'a self,
) -> Result< ) -> Result<