net: Implement canceling of all async operations in FileStream.

net/base/file_stream.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // This file defines FileStream, a basic interface for reading and writing files
 // synchronously or asynchronously with support for seeking to an offset.
 // Note that even when used asynchronously, only one operation is supported at
 // a time.
 
 #ifndef NET_BASE_FILE_STREAM_H_
@@ skipping 23 matching lines @@
   // attached.  |net_log| may be NULL if no logging is needed.
   explicit FileStream(net::NetLog* net_log);
 
   // Construct a FileStream with an existing file handle and opening flags.
   // |file| is valid file handle.
   // |flags| is a bitfield of base::PlatformFileFlags when the file handle was
   // opened.
   // |net_log| is the net log pointer to use to create a |BoundNetLog|.  May be
   // NULL if logging is not needed.
   // The already opened file will not be automatically closed when FileStream
-  // is destructed.
+  // is destroyed.
+  // Note: if you use this constructor you have 3 options of further usage:
+  // - Only sync operations are used on this stream;
+  // - You wait for completion of all async operations;
+  // - When you finished using stream you call any type of Close*() method
+  //   (including possibly CloseAndCancelAsync() or Close() with later
+  //   destruction without waiting for closing callback).
+  // If your usage doesn't fall into one of 3 options above you are introducing
+  // use-after-free bug when file descriptor could be used after you close it
+  // (and it possibly gets reopened to another file).
   FileStream(base::PlatformFile file, int flags, net::NetLog* net_log);
 
   // If the file stream was opened with Open() or OpenSync(), the underlying
   // file will be closed automatically by the destructor, if not closed
   // manually.
   virtual ~FileStream();
 
   // Call this method to close the FileStream, which was previously opened in
   // the async mode (PLATFORM_FILE_ASYNC) asynchronously.
   //
   // Once the operation is done, |callback| will be run on the thread where
   // Close() was called, with OK (i.e. an error is not propagated just like
   // CloseSync() does not).
   //
   // It is not OK to call Close() multiple times. The behavior is not defined.
   // Note that there must never be any pending async operations.
   virtual void Close(const CompletionCallback& callback);
 
   // Call this method to close the FileStream synchronously.
   // It is OK to call CloseSync() multiple times.  Redundant calls are
-  // ignored. Note that if there are any pending async operations, they'll
-  // be aborted.
+  // ignored. Note that if there are any pending async operations, then
+  // behavior of this method is equivalent to CloseAndCancelAsync().
   virtual void CloseSync();
 
+  // Call this method to cancel pending async operations and close FileStream
+  // asynchronously without any notification of completion. Method should be
+  // used when you want to quickly destroy FileStream without actually calling
+  // the destructor.
+  virtual void CloseAndCancelAsync();
+
   // Call this method to open the FileStream asynchronously.  The remaining
   // methods cannot be used unless the file is opened successfully. Returns
   // ERR_IO_PENDING if the operation is started. If the operation cannot be
   // started then an error code is returned.
   //
   // Once the operation is done, |callback| will be run on the thread where
   // Open() was called, with the result code. open_flags is a bitfield of
   // base::PlatformFileFlags.
   //
   // If the file stream is not closed manually, the underlying file will be
@@ skipping 143 matching lines @@
 #elif defined(OS_POSIX)
   FileStreamPosix impl_;
 #endif
 
   DISALLOW_COPY_AND_ASSIGN(FileStream);
 };
 
 }  // namespace net
 
 #endif  // NET_BASE_FILE_STREAM_H_