Avoid memory allocation for PPB_FileIO Read when callback is blocking.

ppapi/api/ppb_file_io.idl

 /* 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 the API to create a file i/o object.
  */
 
@@ skipping 103 matching lines @@
   /**
    * Query() queries info about the file opened by this FileIO object. The
    * FileIO object must be opened, and there must be no other operations
    * pending.
    *
    * @param[in] file_io A <code>PP_Resource</code> corresponding to a
    * FileIO.
    * @param[out] info The <code>PP_FileInfo</code> structure representing all
    * information about the file.
    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
-   * completion of Query().
+   * completion of Query(). If <code>callback</code> is blocking, then
+   * <code>info</code> must remain valid until after the callback runs.

[dmichael (off chromium), 2013/10/22 21:07:51]

This is true not just for blocking callbacks...  and for blocking callbacks,
there really is no callback...

Maybe:
<code>info</code> must remain valud until after callback runs. If you pass a
blocking callback, <code>info</code> must remain valid until after Query
returns.

Similar for Read.

[bbudge, 2013/10/22 22:13:34]

Done.

    *
    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
    * PP_ERROR_FAILED will be returned if the file isn't opened, and
    * PP_ERROR_INPROGRESS will be returned if there is another operation pending.
    */
   int32_t Query([in] PP_Resource file_io,
                 [out] PP_FileInfo info,
                 [in] PP_CompletionCallback callback);
 
   /**
@@ skipping 16 matching lines @@
   int32_t Touch([in] PP_Resource file_io,
                 [in] PP_Time last_access_time,
                 [in] PP_Time last_modified_time,
                 [in] PP_CompletionCallback callback);
 
   /**
    * Read() reads from an offset in the file.  The size of the buffer must be
    * large enough to hold the specified number of bytes to read.  This function
    * might perform a partial read, meaning all the requested bytes
    * might not be returned, even if the end of the file has not been reached.
+   * The FileIO object must have been opened with read access.
    *
    * ReadToArray() is preferred to Read() when doing asynchronous operations.
    *
    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
    * FileIO.
    * @param[in] offset The offset into the file.
    * @param[in] buffer The buffer to hold the specified number of bytes read.
    * @param[in] bytes_to_read The number of bytes to read from
    * <code>offset</code>.
    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
-   * completion of Read().
+   * completion of Read(). If <code>callback</code> is blocking, then
+   * <code>buffer</code> must remain valid until after the callback runs.
    *
    * @return The number of bytes read or an error code from
    * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was
    * reached. It is valid to call Read() multiple times with a completion
    * callback to queue up parallel reads from the file, but pending reads
    * cannot be interleaved with other operations.
    */
   int32_t Read([in] PP_Resource file_io,
                [in] int64_t offset,
                [inout] str_t buffer,
@@ skipping 71 matching lines @@
    * Close().
    *
    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
    * FileIO.
    */
   void Close([in] PP_Resource file_io);
 
   /**
    * ReadToArray() reads from an offset in the file.  A PP_ArrayOutput must be
    * provided so that output will be stored in its allocated buffer.  This
-   * function might perform a partial read.
+   * function might perform a partial read. The FileIO object must have been
+   * opened with read access.
    *
    * @param[in] file_io A <code>PP_Resource</code> corresponding to a file
    * FileIO.
    * @param[in] offset The offset into the file.
    * @param[in] max_read_length The maximum number of bytes to read from
    * <code>offset</code>.
    * @param[in] output A <code>PP_ArrayOutput</code> to hold the output data.
    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
    * completion of ReadToArray().
    *
    * @return The number of bytes read or an error code from
    * <code>pp_errors.h</code>. If the return value is 0, then end-of-file was
    * reached. It is valid to call ReadToArray() multiple times with a completion
    * callback to queue up parallel reads from the file, but pending reads
    * cannot be interleaved with other operations.
    */
   [version = 1.1]
   int32_t ReadToArray([in] PP_Resource file_io,
                       [in] int64_t offset,
                       [in] int32_t max_read_length,
                       [inout] PP_ArrayOutput output,
                       [in] PP_CompletionCallback callback);
 };