Repository: diesel-rs/diesel
File: diesel/src/pg/connection/mod.rs (Rust)

Code before:
                    .instrumentation
                    .on_connection_event(InstrumentationEvent::FinishQuery {
                        query: &crate::debug_query(&source),
                        error: Some(e),
                    });
            }
        }

        f(
            query?,
            binds,
            &mut self.connection_and_transaction_manager,
            source,
        )
    }

    fn set_config_options(&mut self) -> QueryResult<()> {
        crate::sql_query("SET TIME ZONE 'UTC'").execute(self)?;
        crate::sql_query("SET CLIENT_ENCODING TO 'UTF8'").execute(self)?;
        self.connection_and_transaction_manager
            .raw_connection
            .set_notice_processor(noop_notice_processor);
        Ok(())
    }

    /// See Postgres documentation for SQL commands Notify and Listen
    /// The returned iterator can yield items even after a None value when new notifications have been received.
    pub fn notifications_iter(&self) -> NotificationsIterator<'_> {
        NotificationsIterator {
            conn: &self.connection_and_transaction_manager.raw_connection,
        }
    }
}

#[allow(missing_debug_implementations)]
pub struct NotificationsIterator<'a> {
    conn: &'a RawConnection,
}

pub use raw::PGNotification;

impl Iterator for NotificationsIterator<'_> {
    type Item = PGNotification;

    fn next(&mut self) -> Option<Self::Item> {
        self.conn.pqnotifies()
    }
}

extern "C" fn noop_notice_processor(_: *mut libc::c_void, _message: *const libc::c_char) {}


Review comment (suggestion):
It would be good to link the postgres documentation here

It would be even better to have the code from the example as example code in the doc tests.

Code after:
                self.connection_and_transaction_manager
                    .instrumentation
                    .on_connection_event(InstrumentationEvent::FinishQuery {
                        query: &crate::debug_query(&source),
                        error: Some(e),
                    });
            }
        }

        f(
            query?,
            binds,
            &mut self.connection_and_transaction_manager,
            source,
        )
    }

    fn set_config_options(&mut self) -> QueryResult<()> {
        crate::sql_query("SET TIME ZONE 'UTC'").execute(self)?;
        crate::sql_query("SET CLIENT_ENCODING TO 'UTF8'").execute(self)?;
        self.connection_and_transaction_manager
            .raw_connection
            .set_notice_processor(noop_notice_processor);
        Ok(())
    }

    /// See Postgres documentation for SQL commands [NOTIFY][] and [LISTEN][]
    ///
    /// The returned iterator can yield items even after a None value when new notifications have been received.
    /// The iterator can be polled again after a `None` value was received as new notifications might have
    /// been send in the mean time.
    ///
    /// [NOTIFY]: https://www.postgresql.org/docs/current/sql-notify.html
    /// [LISTEN]: https://www.postgresql.org/docs/current/sql-listen.html
    ///
    /// ## Example
    ///
    /// ```
    /// # include!("../../doctest_setup.rs");
    /// #
    /// # fn main() {
    /// #     run_test().unwrap();
    /// # }
    /// #
    /// # fn run_test() -> QueryResult<()> {
    /// #     let connection = &mut establish_connection();
    ///
    /// // register the notifications channel we want to receive notifications for
    /// diesel::sql_query("LISTEN example_channel").execute(connection)?;
    /// // send some notification
    /// // this is usually done from a different connection/thread/application