file_watcher.h

// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

// Date: 2010/05/29

// Watch timestamp of a file

#ifndef BUTIL_FILES_FILE_WATCHER_H
#define BUTIL_FILES_FILE_WATCHER_H

#include <stdint.h>                                 // int64_t
#include <string>                                   // std::string

// Example:
//   FileWatcher fw;
//   fw.init("to_be_watched_file");
//   ....
//   if (fw.check_and_consume() > 0) {
//       // the file is created or updated 
//       ......
//   }

namespace butil {
class FileWatcher {
public:
    enum Change {
        DELETED = -1,
        UNCHANGED = 0,
        UPDATED = 1,
        CREATED = 2,
    };

    typedef int64_t Timestamp;
    
    FileWatcher();

    // Watch file at `file_path', must be called before calling other methods.
    // Returns 0 on success, -1 otherwise.
    int init(const char* file_path);
    // Let check_and_consume returns CREATE when file_path already exists.
    int init_from_not_exist(const char* file_path);

    // Check and consume change of the watched file. Write `last_timestamp'
    // if it's not NULL.
    // Returns:
    //   CREATE    the file is created since last call to this method.
    //   UPDATED   the file is modified since last call.
    //   UNCHANGED the file has no change since last call.
    //   DELETED   the file was deleted since last call.
    // Note: If the file is updated too frequently, this method may return 
    // UNCHANGED due to precision of stat(2) and the file system. If the file
    // is created and deleted too frequently, the event may not be detected.
    Change check_and_consume(Timestamp* last_timestamp = NULL);

    // Set internal timestamp. User can use this method to make
    // check_and_consume() replay the change.
    void restore(Timestamp timestamp);
    
    // Get path of watched file
    const char* filepath() const { return _file_path.c_str(); }

private:
    Change check(Timestamp* new_timestamp) const;

    std::string _file_path;
    Timestamp _last_ts;    
};
}  // namespace butil

#endif  // BUTIL_FILES_FILE_WATCHER_H