@ohos-ports/fd 0.0.3-beta.1

package/LICENSE

@@ -0,0 +1,39 @@
+Copyright 2012, Rod Vagg (the "Original Author")
+All rights reserved.
+
+MIT +no-false-attribs License
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+Distributions of all or part of the Software intended to be used
+by the recipients as they would use the unmodified Software,
+containing modifications that substantially alter, remove, or
+disable functionality of the Software, outside of the documented
+configuration mechanisms provided by the Software, shall be
+modified such that the Original Author's bug reporting email
+addresses and urls are either replaced with the contact information
+of the parties responsible for the changes, or removed entirely.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+
+Except where noted, this license applies to any and all software
+programs and associated documentation files created by the
+Original Author, when distributed with the Software.

package/README.md

@@ -0,0 +1,122 @@
+# fd [![Build Status](https://secure.travis-ci.org/rvagg/node-fd.png)](http://travis-ci.org/rvagg/node-fd)
+
+File descriptor manager for Node.js. *Available in npm as <strong>fd</strong>*.
+
+**fd** manages `fs.open()` and `fs.close()` calls safely for you where there may be timing issues related to multiple-use of the same descriptor.
+
+**fd** provides `checkin()` and `checkout()` functions so your application can register its intent to use a file descriptor after it's been opened and then register that it has finished with the descriptor so that any pending `fs.close()` operations may be performed.
+
+**fd** naturally couples with [async-cache](https://github.com/isaacs/async-cache) to provide a safe pool of file descriptors.
+
+## Example
+
+Lets make a static resource web server! This example can be found in the *example/* directory of this repository.
+
+We use [async-cache](https://github.com/isaacs/async-cache) to cache both `fs.sync()` calls and `fd`s, but we hook it up to **fd** so we can safely manage opens and closes.
+
+```js
+const fdman = require('fd')()
+    , http  = require('http')
+    , fs    = require('fs')
+    , path  = require('path')
+    , AC    = require('async-cache')
+    , mime  = require('mime')
+
+    , ROOT  = path.join(__dirname, 'public')
+
+      // an async cache for fs.stat calls, fresh for 10s
+    , statCache = AC({
+          max    : 100
+        , maxAge : 10000
+        , load   : function (path, callback) {
+                     fs.stat(path, callback)
+                   }
+      })
+
+      // an async cache for fds, fresh for 10s
+    , fdCache = AC({
+          max     : 100
+        , maxAge  : 10000
+          // use fdman to open & close
+        , load    : fdman.open.bind(fdman)
+        , dispose : fdman.close.bind(fdman)
+      })
+
+    , serveError = function (res) {
+        res.statusCode = 404
+        res.setHeader('content-type', 'text/plain')
+        res.end(http.STATUS_CODES[res.statusCode] + '\n')
+      }
+
+http.createServer(function (req, res) {
+  var p = path.join(ROOT, req.url)
+
+  // get a fs.stat for this file
+  statCache.get(p, function (err, stat) {
+    if (err || !stat.isFile())
+      return serveError(res)
+
+    // get an fd for this file
+    fdCache.get(p, function (err, fd) {
+      var mimeType = mime.lookup(path.extname(p))
+          // get a safe checkin function from fdman that
+          // we could safely all multiple times for this single
+          // checkout
+        , checkin = fdman.checkinfn(p, fd)
+
+      // check out the fd for use
+      fdman.checkout(p, fd)
+
+      res.setHeader(
+          'content-type'
+          // don't force download, just show it
+        , mimeType != 'application/octet-stream' ? mimeType : 'text/plain'
+      )
+
+      // stream from the fd to the response
+      var st = fs.createReadStream(p, { fd: fd, start: 0, end: stat.size })n
+        .on('end', checkin)
+        .on('error', checkin)
+
+      // override destroy so we don't close the fd
+      st.destroy = function () {}
+
+      st.pipe(res)
+
+    })
+  })
+}).listen(8080)
+```
+
+## API
+
+### fd()
+Create a new instance of **fd**. Typically called with `var fdman = require('fd')()`. You can have multiple, separate instances of **fd** operating at the same time, hence the need to instantiate.
+
+### fdman.open(path, callback)
+Equivalent to `fs.open(path, callback)`, you'll get back an `err` and `fd` parameters but the descriptor will go into the managed pool.
+
+### fdman.close(path, fd)
+Will call `fs.close(fd)` *only when the `fd` is no longer in use*. i.e. it will wait till all current uses have been checked in (see below).
+
+### fdman.checkout(path, fd)
+Called when your application may need to use the `fd`. This should be called as early as possible, even if your application may not end up using it.
+
+It is important to perform a `checkout()` as soon as you have a reference to the file descriptor if you may be using it, otherwise an asynchronous call may interrupt and call `close()` before you use it. You *don't have to use the `fd`* to register your intent to use it, as long as you eventually call `checkin()`.
+
+### fdman.checkin(path, fd)
+Register with **fd** that you have finished using the descriptor and it can be safely closed if need be.
+
+The descriptor may not need to be closed or there may be other uses of the descriptor currently checked out so a `checkin()` won't automatically lead to a `close()`.
+
+### fdman.checkinfn(path, fd)
+Returns a function that, when called, will safely perform a `checkin()` for you on the given path and descriptor. An important property of the function is that it will only perform a single `checkin()` regardless of how many times it is called.
+
+This returned function is helpful for calling `checkin()` from multiple points in your application, such as in case of error, and you don't need to worry about whether it's been previously called for the current `checkout()`.
+
+See the example above how this can be used.
+
+
+## Licence
+
+fd is Copyright (c) 2012 Rod Vagg [@rvagg](https://twitter.com/rvagg) and licenced under the MIT licence. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.

package/index.js

@@ -0,0 +1,175 @@
+const fs = require('fs')
+
+var totalOpenFds = 0 // across all instances
+
+    // the reason we use a combination of path+fd to store references
+    // in this._fds is that it is possible to have multiple fds
+    // for the same file simultaneously. Particularly in the situation
+    // where an fd is pending for a close but hasn't been checked back
+    // in by all clients
+  , key          = function (path, fd) {
+      return fd + ':' + path
+    }
+
+    // actually close the fd and forget all bookkeeping for it
+  , cleanupFd    = function (path, fd) {
+      var k = key(path, fd)
+
+      delete this._fds[k]
+      // only remove the path entry when it actually points at *this* fd,
+      // otherwise we would pull the rug out from under a newer fd that
+      // was opened for the same path while this one was being closed
+      if (this._fds[path] === fd)
+        delete this._fds[path]
+
+      if (this._pendingClose[k]) {
+        fs.close(fd, function () {})
+        totalOpenFds--
+        delete this._pendingClose[k]
+        delete this._everCheckedOut[k]
+        delete this._syncWindow[k]
+        delete this._syncCheckout[k]
+      }
+    }
+
+    // forget the bookkeeping for an fd that has gone idle *without* closing
+    // it: more checkouts may still follow (a close() request does not stop
+    // new checkouts), and closing it here - or in any timed "idle" window -
+    // races with those future checkouts. when such a close-then-checkout
+    // race is lost the OS re-uses the closed fd number for another file and
+    // the outstanding user reads the wrong file's contents. the fd is
+    // therefore deliberately left open and merely marked via _pendingClose
+    // so open() will hand out a fresh fd for the path instead of the old one
+  , forgetFd     = function (path, fd) {
+      var k = key(path, fd)
+
+      delete this._fds[k]
+      if (this._fds[path] === fd)
+        delete this._fds[path]
+    }
+
+  , close       = function (path, fd) {
+      // dispose of this fd when possible
+
+      var k = key(path, fd)
+
+      this._pendingClose[k] = fd
+      // nextTick needed to match the nextTick in an async-cache otherwise we may
+      // close it in the tick prior to it being actually needed
+      process.nextTick(function () {
+        // only ever *really* close an fd that has never been checked out:
+        // nobody can be using it and no future checkout can be pending for
+        // it, so this is the one case where closing is provably safe. for
+        // fds that have been checked out we cannot know whether another
+        // checkout (which may legitimately follow a close request) is still
+        // to come, and timer-based "idle grace" windows are unreliable under
+        // load (timers fire out of order / in bursts), so those fds are kept
+        // open for the lifetime of the manager and simply excluded from
+        // reuse by the _pendingClose marker
+        if (!this._fds[k] && !this._everCheckedOut[k])
+          cleanupFd.call(this, path, fd)
+      }.bind(this))
+    }
+
+  , open        = function (path, cb) {
+      // open a new fd
+
+      // if the file is already open and in use but not with a close pending
+      // then just use that.
+      if (this._fds[path] && !this._pendingClose[key(path, this._fds[path])])
+        return cb(null, this._fds[path])
+
+      fs.open(path, 'r', function (er, fd) {
+        var k = key(path, fd)
+
+        if (!er) {
+          totalOpenFds++
+          this._fds[path] = fd
+          this._fds[key(path, fd)] = 0
+          // mark the current turn as the fd's "synchronous window": a
+          // checkout performed synchronously within this open callback (the
+          // documented open() -> checkout() -> close() -> checkin() pattern)
+          // is one whose lifetime the caller fully controls, so the pending
+          // close can be honoured the moment that checkout is checked back
+          // in. checkouts that happen in later turns (timers etc.) may be
+          // followed by yet more checkouts, so they opt out of that
+          this._syncWindow[k] = true
+          process.nextTick(function () {
+            delete this._syncWindow[k]
+          }.bind(this))
+        }
+
+        cb(er, fd)
+      }.bind(this))
+    }
+
+  , checkout     = function (path, fd) {
+      // call whenever you *may* be about to use the fd, to ensure it's not cleaned up
+
+      var k     = key(path, fd)
+        , count = this._fds[k] = (this._fds[k] || 0) + 1
+
+      this._fds[path] = fd
+      this._everCheckedOut[k] = true
+      if (this._syncWindow[k])
+        this._syncCheckout[k] = true
+      else
+        // an out-of-turn checkout means the fd may see yet more checkouts
+        // after a close() request, so the close may not be honoured at the
+        // next checkin (see checkin() and forgetFd())
+        this._syncCheckout[k] = false
+    }
+
+  , checkin     = function (path, fd) {
+      // call sometime after checkout() when you know you're not using it
+
+      var k = key(path, fd)
+
+      if (this._fds[path] && --this._fds[k] === 0) {
+        if (this._pendingClose[k] && this._syncCheckout[k]) {
+          // documented pattern: open() -> checkout() in the open callback ->
+          // close() -> checkin(). every checkout of this fd happened inside
+          // the open callback, so once it's checked back in nothing can
+          // possibly use it anymore - close it right now
+          cleanupFd.call(this, path, fd)
+        } else {
+          // fd went idle, but it has seen (or may still see) checkouts from
+          // outside the open callback, so a pending close must not be
+          // honoured here - just forget the entries and keep the fd alive
+          forgetFd.call(this, path, fd)
+        }
+      }
+    }
+
+  , checkinfn   = function (path, fd) {
+      // make a checkin function that can be safely called multiple times
+
+      var called = false
+      return function () {
+        if (!called) {
+          this.checkin(path, fd)
+          called = true
+        }
+      }.bind(this)
+    }
+
+  , FDManager   = {
+        open      : open
+      , close     : close
+      , checkout  : checkout
+      , checkin   : checkin
+      , checkinfn : checkinfn
+    }
+
+  , create      = function () {
+      return Object.create(FDManager, {
+          _fds            : { value: Object.create(null) }
+        , _pendingClose   : { value: Object.create(null) }
+        , _everCheckedOut : { value: Object.create(null) }
+        , _syncWindow     : { value: Object.create(null) }
+        , _syncCheckout   : { value: Object.create(null) }
+      })
+    }
+
+module.exports               = create
+module.exports._totalOpenFds = totalOpenFds

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ohos-ports/fd",
+  "description": "File descriptor manager",
+  "version": "0.0.3-beta.1",
+  "homepage": "https://github.com/rvagg/node-fd",
+  "authors": [
+    "Rod Vagg <rod@vagg.org> (https://github.com/rvagg)"
+  ],
+  "keywords": [
+    "fd",
+    "fs",
+    "descriptor",
+    "file"
+  ],
+  "main": "./index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ohos-ports/ohos-ports.git",
+    "directory": "ports/fd/0.0.3"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "tap": "*",
+    "sinon": "*",
+    "mkfiletree": "*"
+  },
+  "scripts": {
+    "test": "tap test.js"
+  },
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "LICENSE",
+    "README.md"
+  ]
+}