Struct watchman_client::Client

pub struct Client { /* private fields */ }

A live connection to a watchman server. Use Connector to establish a connection.

Implementations

impl Client

pub async fn state_enter(
    &self,
    root: &ResolvedRoot,
    state_name: &str,
    sync_timeout: SyncTimeout,
    metadata: Option<Value>
) -> Result<(), Error>

This method will attempt to assert the state named state_name on the watchman server. This is used to facilitate advanced settling in subscriptions.

Only one client can assert a given named state for a given root at a given time; an error will be returned if another client owns the requested state assertion.

If successful, the state will remain asserted until the owning client either issues a state-leave or disconnects from the server.

The optional metadata will be published to all subscribers of the root and made visible via SubscriptionData::StateEnter::metadata.

See also: https://facebook.github.io/watchman/docs/cmd/state-enter.html

pub async fn state_leave(
    &self,
    root: &ResolvedRoot,
    state_name: &str,
    sync_timeout: SyncTimeout,
    metadata: Option<Value>
) -> Result<(), Error>

This method will attempt to release an owned state assertion for the state named state_name on the watchman server. This is used to facilitate advanced settling in subscriptions.

The optional metadata will be published to all subscribers of the root and made visible via SubscriptionData::StateLeave::metadata.

See also: https://facebook.github.io/watchman/docs/cmd/state-leave.html

pub async fn resolve_root(
    &self,
    path: CanonicalPath
) -> Result<ResolvedRoot, Error>

This is typically the first method invoked on a client. Its purpose is to ensure that the watchman server is watching the specified path and to resolve it to a ResolvedRoot instance.

The path to resolve must be a canonical path; watchman performs strict name resolution to detect TOCTOU issues and will generate an error if the path is not the canonical name.

Note that for regular filesystem watches, if the requested path is not yet being watched, this method will not yield until the watchman server has completed a recursive crawl of that portion of the filesystem. In other words, the worst case performance of this is O(recursive-number-of-files) and is impacted by the underlying storage device and its performance characteristics.

pub async fn query<F>(
    &self,
    root: &ResolvedRoot,
    query: QueryRequestCommon
) -> Result<QueryResult<F>, Error> where
    F: DeserializeOwned + Debug + Clone + QueryFieldList, 

Perform a generic watchman query. The F type is a struct defined by the query_result_type! macro, or, if you want only the file name from the results, the NameOnly struct.

use watchman_client::prelude::*;
use serde::Deserialize;

query_result_type! {
    struct NameAndType {
        name: NameField,
        file_type: FileTypeField,
    }
}

async fn query(
   client: &mut Client,
   resolved: &ResolvedRoot
) -> Result<(), Box<dyn std::error::Error>> {
   let response: QueryResult<NameAndType> = client
       .query(
           &resolved,
              QueryRequestCommon {
               glob: Some(vec!["**/*.rs".to_string()]),
               ..Default::default()
           },
       )
       .await?;
   println!("response: {:#?}", response);
   Ok(())
}

When constructing your result type, you can select from the following fields:

• CTimeAsFloatField
• CTimeField
• ContentSha1HexField
• CreatedClockField
• DeviceNumberField
• ExistsField
• FileTypeField
• InodeNumberField
• MTimeAsFloatField
• MTimeField
• ModeAndPermissionsField
• NameField
• NewField
• NumberOfLinksField
• ObservedClockField
• OwnerGidField
• OwnerUidField
• SizeField
• SymlinkTargetField

(See the fields module for a definitive list)

The file names are all relative to the root parameter.

pub async fn subscribe<F>(
    &self,
    root: &ResolvedRoot,
    query: SubscribeRequest
) -> Result<(Subscription<F>, SubscribeResponse), Error> where
    F: DeserializeOwned + Debug + Clone + QueryFieldList, 

Create a Subscription that will yield file changes as they occur in real time. The F type is a struct defined by the query_result_type! macro, or, if you want only the file name from the results, the NameOnly struct.

Returns two pieces of information:

• A Subscription handle that can be used to yield changes as they are observed by watchman
• A SubscribeResponse that contains some data about the state of the watch at the time the subscription was initiated

pub async fn glob(
    &self,
    root: &ResolvedRoot,
    globs: &[&str]
) -> Result<Vec<PathBuf>, Error>

Expand a set of globs into the set of matching file names. The globs must be relative to the root parameter. The returned file names are all relative to the root parameter.

pub async fn clock(
    &self,
    root: &ResolvedRoot,
    sync_timeout: SyncTimeout
) -> Result<ClockSpec, Error>

Returns the current clock value for a watched root. If sync_timeout is SyncTimeout::DisableCookie then the instantaneous clock value is returned without using a sync cookie.

Otherwise, a sync cookie will be created and the server will wait for up to the associated sync_timeout duration to observe it. If that timeout is reached, this method will yield an error.

When should you use a cookie? If you need to a clock value that is guaranteed to reflect any filesystem changes that happened before a given point in time you should use a sync cookie.

See also:

• https://facebook.github.io/watchman/docs/cmd/clock.html
• https://facebook.github.io/watchman/docs/cookies.html

pub async fn get_config(
    &self,
    root: &ResolvedRoot
) -> Result<WatchmanConfig, Error>

Returns the current configuration for a watched root.