index.html 12.3 KB

原文件审查历史永久链接

<!DOCTYPE html>
<html lang='en'>
  <head>
    <meta charset='utf-8'>
    <title>synchronize.js</title>
    <meta name='viewport' content='width=device-width, initial-scale=1.0'>
    <meta name='description' content=''>
    <meta name='author' content=''>

    <!-- Styles -->
    <link href='assets/bootstrap/css/bootstrap.css' rel='stylesheet'>
    <link href='assets/google-code-prettify/prettify.css' rel='stylesheet'>
    <link href='assets/style.css' rel='stylesheet'>

    <!-- HTML5 shim, for IE6-8 support of HTML5 elements -->
    <!--[if lt IE 9]>
      <script src='http://html5shim.googlecode.com/svn/trunk/html5.js'></script>
    <![endif]-->
  </head>

  <body>

    <!-- <div class='navbar navbar-fixed-top'>
      <div class='navbar-inner'>
        <div class='container'>
          <a class='brand' href='#'>synchronize.js</a>
          <ul class='nav'>
            <li class='active'><a href='#'>Home</a></li>
            <li><a href='#about'>About</a></li>
            <li><a href='#contact'>Contact</a></li>
          </ul>
        </div>
      </div>
    </div> -->

    <div class='container'>

<!-- <pre class='prettyprint'>
a = function(){
  console.log('hi')
}
</pre> -->

      <div class='row'>
        <div class='offset1 span10'>

          <!-- Overview -->
          <div class='page-header'>
            <h1>
              synchronize.js
              <small>write asynchronous code as if it's synchronous</small>
            </h1>
          </div>
          <p>
            Use <code>await</code> and <code>defer</code> to execute asynchronous functions
            synchronously.
          </p>
          <p>
            Synchronize assumes node-style <code>(err, result)</code> callbacks.
            The second parameter given to the cb will be returned.
            If an error is present it will be thrown and can be intercepted by a try/catch statement.
            Multiple and named arguments are supported with <code>defers</code>.
          </p>
          <p>
            You can use the helper <code>sync(fn)</code> and it will use await/defer
            automatically.
            The helper is non-destructive and the function can still be called asynchronously
            if called with a callback.
            You can also mix it with other synchronous or asynchronous code.
          </p>
          <p>
            Use <code>await</code>/<code>defer</code> manually to get precise control or automatically to write compact and clean code.
          </p>

          <p>
            Install it with <code>npm install synchronize</code>.
          </p>

          <p>
            The project is hosted on
            <a href='http://github.com/alexeypetrushin/synchronize'>GitHub</a>.
            <br>
            You can report bugs and discuss features on the
            <a href='http://github.com/alexeypetrushin/synchronize/issues'>Issues</a> page.
          </p>

          <!-- How to use -->
          <h2>Usage patterns</h2>
          <div class='row'>
            <div class='span5'>
<pre class='prettyprint'>
data = sync.await(fs.readFile(fname, sync.defer()))
</pre>
            </div>
            <div class='span5'>
              <p>
                Use <code>await</code> and <code>defer</code> keywords by hand
                to call a function synchronously (you can make await and defer global
                to make things shorter).
              </p>
            </div>
          </div>
          <div class='row' style="margin-top: 10px">
            <div class='span5'>
<pre class='prettyprint'>
sync(fs, 'readFile')

var data = fs.readFile(fname)
fs.readFile(fname, function(err, data)){}
</pre>
            </div>
            <div class='span5'>
              <p>
                Use <code>sync()</code> to make an async function synchronize.js-aware.
                You can use it in both ways - synchronous or asynchronous.
                Basically it uses the same await/defer pattern, but automatically.
                This object form preserves context, unlike the form below.
              </p>
            </div>
          </div>
          <div class='row' style="margin-top: 10px">
            <div class='span5'>
<pre class='prettyprint'>
asyncFn = sync(asyncFn)

var data = asyncFn(input)
// You can still use the async form of this fn
var data = sync.await(asyncFn(input, sync.defer()))
asyncFn(input, function(err, data){})
</pre>
            </div>
            <div class='span5'>
              <p>
                You can use <code>sync()</code> on a bare function to return
                a synchronized version of the function. It can still be used
                in asynchronous form.
              </p>
            </div>
          </div>

          <!-- Samples -->

          <h2>Basic usage, printing content of file</h2>

          <div class='row'>
            <div class='span5'>
<pre class='prettyprint'>
var sync = require('synchronize')
var fs   = require('fs')

sync(fs, 'readFile')

sync.fiber(function(){
  var data = fs.readFile(__filename, 'utf8')
  console.log(data)

  try {
    data = fs.readFile('invalid', 'utf8')
  } catch (err) {
    console.log(err)
  }

  fs.readFile(__filename, 'utf8', function(err, data){
    console.log(data)
  })
})
</pre>
            </div>
            <div class='span5'>
              <p>
                In order to use synchronized functions and pause execution without blocking Node.js we
                need to wrap execution into a <code>Fiber</code> using <code>sync.fiber()</code>.
              </p>
              <p style="margin-top:50px">
                Inside of Fiber we can call asynchronous functions as if it's synchronous.
              </p>
              <p style="margin-top:30px">
                We can also use standard try/catch statements to catch asynchronous errors.
              </p>
              <p style="margin-top:70px">
                Or call readFile asynchronously if we wish.
              </p>
            </div>
          </div>

          <h2>Listing and printing files in directory</h2>
          <p>
            Listing content of current directory, checking if path is file and printing its content
            to console.
          </p>
          <div class='row'>
            <div class='span5'>
              <h3>Using synchronize</h3>
<pre class='prettyprint'>
var sync = require('synchronize')
var fs   = require('fs')

sync(fs, 'readdir', 'stat', 'readFile')

sync.fiber(function(){
  var i, paths, path, stat, data
  paths = fs.readdir('.')
  for(i = 0; i < paths.length; i++){
    path = paths[i]
    stat = fs.stat(path)
    if(!stat.isFile()) continue
    data = fs.readFile(path, 'utf8')
    console.log(data)
  }
})
</pre>
            </div>
            <div class='span5'>
              <h3>The same code without synchronization</h3>
<pre class='prettyprint'>
var fs = require('fs')

var printFile = function(paths, i){
  if(i >= paths.length) return
  var path = paths[i]
  fs.stat(path, function(err, stat){
    if(err) throw err
    if(stat.isFile()){
      fs.readFile(path, 'utf8', function(err, data){
        if(err) throw err
        console.log(data)
        printFile(paths, i + 1)
      })
    } else {
      printFile(paths, i + 1)
    }
  })
}

fs.readdir('.', function(err, paths){
  if(err) throw err
  printFile(paths, 0)
})
</pre>
            </div>
          </div>

          <h2>Parallel and serial operations</h2>
          <p>
            Synchronize.js can run multiple operations in parallel using
            <code>sync.parallel()</code>.
          </p>
          <div class='row'>
            <div class='span5'>
              <h3>Async operations in serial</h3>
<pre class='prettyprint'>
var sync = require('synchronize')

var read = function(a, cb) {
  setTimeout(function(){
    // remember that callbacks expect (err, result)
    cb(null, a)
  }, 1000)
}

// We can use the `sync` helper here to avoid using
// `await()` and `defer()` manually.
read = sync(read);

sync.fiber(function() {
  var results = []
  results.push(read(1)))
  results.push(read(2)))
  // results now contains [1,2]
})
</pre>
            </div>
            <div class='span5'>
              <h3>Async operations in parallel</h3>
<pre class='prettyprint'>
var sync = require('synchronize')

function read(a, cb) {
  setTimeout(function(){
    cb(null, a)
  }, 1000)
}

// Runs in parallel
sync.fiber(function() {
  sync.parallel(function() {
    // You must call defer() manually within
    // a parallel operation.
    read(1, sync.defer())
    read(2, sync.defer())
  });
  var results = sync.await()
  // results now contains [1,2]
});
</pre>
            </div>
          </div>

          <h2>Multiple arguments in callbacks</h2>
          <p>
            Synchronize.js accepts multiple arguments in callbacks using <code>sync.defers()</code>.
          </p>
          <div class='row'>
            <div class='span5'>
              <h3>Multiple arguments in serial</h3>
<pre class='prettyprint'>
var sync = require('synchronize')

function read(a, b, c, cb) {
  setTimeout(function(){
    cb(null, a, b, c)
  }, 1000)
}

sync.fiber(function() {
  // Returns [1,2,3]
  var results = sync.await(
    read(1, 2, 3, sync.defers()))
  // Returns {a: 4, b: 5, c: 6}
  var namedResults = sync.await(
    read(4, 5, 6, sync.defers('a', 'b', 'c')))
})
</pre>
            </div>
            <div class='span5'>
              <h3>Multiple arguments in parallel</h3>
<pre class='prettyprint'>
var sync = require('synchronize')

function read(a, b, c, cb) {
  setTimeout(function(){
    cb(null, a, b, c)
  }, 1000)
}

sync.fiber(function() {
  sync.parallel(function(){
    read(1, 2, 3, sync.defers())
    read(4, 5, 6, sync.defers())
  });
  // returns [[1,2,3],[4,5,6]]
  var results = sync.await()
  // concat to get [1,2,3,4,5,6]
  results = [].concat.apply([], results)
})
</pre>
            </div>
          </div>


          <h2>Usage with Express.js</h2>
          <div class='row'>
            <div class='span5'>
<pre class='prettyprint'>
var sync    = require('synchronize')
var fs      = require('fs')
var express = require('express')

sync(fs, 'readFile')

var app = express.createServer()
app.use(function(req, res, next){
  sync.fiber(next)
})

app.get('/', function(req, res){
  var data = fs.readFile(__filename, 'utf8')
  res.send(data, {'Content-Type': 'text/plain'})
})

app.listen(3000)
</pre>
            </div>
            <div class='span5'>
              <p>Synchronized code can be mixed with asynchronous code in any combination.</p>
              <p>
                Here is one possible way to use it with Express.js.</p>
            </div>
          </div>

          <h2>Usage with Mocha.js</h2>
          <div class='row'>
            <div class='span5'>
<pre class='prettyprint'>
var sync  = require('synchronize')
var fs    = require('fs')

sync(fs, 'readFile')

var async = sync.asyncIt

describe('File System', function(){
  it('should read file', async(function(){
    var data = fs.readFile(__filename, 'utf8')
  }))
})
</pre>
            </div>
            <div class='span5'>
              <p>
                You can use the <code>sync.asyncIt</code> helper to greatly simplify writing
                asynchronous tests.
              </p>

              <p>
                You may also take a look at
                <a href='https://github.com/alexeypetrushin/mongo-lite/blob/master/test/collection.coffee'>
                  this real-life test scenario</a>
                that uses synchronize to simplify asynchronous calls for MongoDB.
              </p>
            </div>
          </div>

          <!-- How to use -->
          <h2>Similar tools</h2>
          <p>
            <a href="http://monojs.org">MonoJS</a> - synchronous web framework based on synchronize.
          </p>

          <hr/>

          <p>Copyright <a href='http://petrush.in'>Alexey Petrushin</a>, released under MIT License</p>
        </div>
      </div>

    </div><!-- /container -->

    <a href='http://github.com/alexeypetrushin/synchronize'><img style='position: absolute; top: 0; right: 0; border: 0; z-index: 2080;'  src='https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png' alt='Fork me on GitHub'></a>

    <!-- Scripts -->
    <script src='https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js'></script>
    <script src='assets/bootstrap/js/bootstrap.js'></script>
    <script src='assets/google-code-prettify/prettify.js'></script>
    <script>
      $(prettyPrint)
    </script>
  </body>
</html>