1/* Copyright 2015 The TensorFlow Authors. All Rights Reserved.
2
3Licensed under the Apache License, Version 2.0 (the "License");
4you may not use this file except in compliance with the License.
5You may obtain a copy of the License at
6
7 http://www.apache.org/licenses/LICENSE-2.0
8
9Unless required by applicable law or agreed to in writing, software
10distributed under the License is distributed on an "AS IS" BASIS,
11WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12See the License for the specific language governing permissions and
13limitations under the License.
14==============================================================================*/
15
16#ifndef TENSORFLOW_CORE_UTIL_EVENTS_WRITER_H_
17#define TENSORFLOW_CORE_UTIL_EVENTS_WRITER_H_
18
19#include <memory>
20#include <string>
21
22#include "tensorflow/core/lib/core/status.h"
23#include "tensorflow/core/lib/io/record_writer.h"
24#include "tensorflow/core/platform/env.h"
25#include "tensorflow/core/platform/macros.h"
26#include "tensorflow/core/platform/types.h"
27#include "tensorflow/core/util/event.pb.h"
28
29namespace tensorflow {
30
31class EventsWriter {
32 public:
33#ifndef SWIG
34 // Prefix of version string present in the first entry of every event file.
35 static constexpr const char* kVersionPrefix = "brain.Event:";
36 static constexpr const int kCurrentVersion = 2;
37#endif
38
39 // Events files typically have a name of the form
40 // '/some/file/path/my.file.out.events.[timestamp].[hostname][suffix]'
41 // To create and EventWriter, the user should provide file_prefix =
42 // '/some/file/path/my.file'
43 // The EventsWriter will append '.out.events.[timestamp].[hostname][suffix]'
44 // to the ultimate filename once Init() is called.
45 // Note that it is not recommended to simultaneously have two
46 // EventWriters writing to the same file_prefix.
47 explicit EventsWriter(const std::string& file_prefix);
48 ~EventsWriter();
49
50 // Sets the event file filename and opens file for writing. If not called by
51 // user, will be invoked automatically by a call to FileName() or Write*().
52 // Returns false if the file could not be opened. Idempotent: if file exists
53 // and is open this is a no-op. If on the other hand the file was opened,
54 // but has since disappeared (e.g. deleted by another process), this will open
55 // a new file with a new timestamp in its filename.
56 Status Init();
57 Status InitWithSuffix(const std::string& suffix);
58
59 // Returns the filename for the current events file:
60 // filename_ = [file_prefix_].out.events.[timestamp].[hostname][suffix]
61 std::string FileName();
62
63 // Append "event" to the file. The "tensorflow::" part is for swig happiness.
64 void WriteEvent(const tensorflow::Event& event);
65
66 // Append "event_str", a serialized Event, to the file.
67 // Note that this function does NOT check that de-serializing event_str
68 // results in a valid Event proto. The tensorflow:: bit makes SWIG happy.
69 void WriteSerializedEvent(tensorflow::StringPiece event_str);
70
71 // EventWriter automatically flushes and closes on destruction, but
72 // these two methods are provided for users who want to write to disk sooner
73 // and/or check for success.
74 // Flush() pushes outstanding events to disk. Returns false if the
75 // events file could not be created, or if the file exists but could not
76 // be written too.
77 // Close() calls Flush() and then closes the current events file.
78 // Returns true only if both the flush and the closure were successful.
79 Status Flush();
80 Status Close();
81
82 private:
83 Status FileStillExists(); // OK if event_file_path_ exists.
84 Status InitIfNeeded();
85
86 Env* env_;
87 const std::string file_prefix_;
88 std::string file_suffix_;
89 std::string filename_;
90 std::unique_ptr<WritableFile> recordio_file_;
91 std::unique_ptr<io::RecordWriter> recordio_writer_;
92 int num_outstanding_events_;
93 TF_DISALLOW_COPY_AND_ASSIGN(EventsWriter);
94};
95
96} // namespace tensorflow
97
98#endif // TENSORFLOW_CORE_UTIL_EVENTS_WRITER_H_
99