hadoop-hdfs-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Leif Wickland (JIRA)" <j...@apache.org>
Subject [jira] [Updated] (HDFS-5387) Documentation on FileSystem.createNewFile() is misleading
Date Fri, 18 Oct 2013 17:08:41 GMT

     [ https://issues.apache.org/jira/browse/HDFS-5387?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]

Leif Wickland updated HDFS-5387:
--------------------------------

    Description: 
The documentation for FileSystem.createNewFile() indicates that it will return false if it
failed to create the requested file.  In fact, it will only return false if the file existed
before the function was called.  Also the function fails to mention that a race condition
can result in an exception be thrown if another process attempts to create the file at the
same time.

Here's my suggested improvement to the documentation's wording:

{code}
   /**
-   * Creates the given Path as a brand-new zero-length file.  If
-   * create fails, or if it already existed, return false.
-   *
+   * Creates the given Path as a brand-new zero-length file.  
+   * A race condition can occur inside this function if f is created by another
+   * process after this function has checked for the existence of f. In some
+   * implementations that will result in an exception being thrown. 
    * @param f path to use for create
+   * @return true if the file was created; false if the path already exists.
+   * @throws IOException
    */
   public boolean createNewFile(Path f) throws IOException {
{code}

  was:The documentation for FileSystem.createNewFile() indicates that it will return false
if it failed to create the requested file.  In fact, it will only return false if the file
existed before the function was called.  Also the function fails to mention that a race condition
can result in an exception be thrown if another process attempts to create the file at the
same time.


> Documentation on FileSystem.createNewFile() is misleading
> ---------------------------------------------------------
>
>                 Key: HDFS-5387
>                 URL: https://issues.apache.org/jira/browse/HDFS-5387
>             Project: Hadoop HDFS
>          Issue Type: Improvement
>            Reporter: Leif Wickland
>            Priority: Trivial
>         Attachments: FileSystem.java.patch
>
>
> The documentation for FileSystem.createNewFile() indicates that it will return false
if it failed to create the requested file.  In fact, it will only return false if the file
existed before the function was called.  Also the function fails to mention that a race condition
can result in an exception be thrown if another process attempts to create the file at the
same time.
> Here's my suggested improvement to the documentation's wording:
> {code}
>    /**
> -   * Creates the given Path as a brand-new zero-length file.  If
> -   * create fails, or if it already existed, return false.
> -   *
> +   * Creates the given Path as a brand-new zero-length file.  
> +   * A race condition can occur inside this function if f is created by another
> +   * process after this function has checked for the existence of f. In some
> +   * implementations that will result in an exception being thrown. 
>     * @param f path to use for create
> +   * @return true if the file was created; false if the path already exists.
> +   * @throws IOException
>     */
>    public boolean createNewFile(Path f) throws IOException {
> {code}



--
This message was sent by Atlassian JIRA
(v6.1#6144)

Mime
View raw message