37 |
38 |
43 |
44 |
427 |
428 |
45 |
425 |
426 |
46 |
47 |
48 |
421 | 422 |
424 |
49 |
54 | 50 | synchronize.js 51 | write asynchronous code as if it's synchronous 52 |
53 |
55 | Use await and defer to execute asynchronous functions
56 | synchronously.
57 |
59 | Synchronize assumes node-style (err, result) callbacks.
60 | The second parameter given to the cb will be returned.
61 | If an error is present it will be thrown and can be intercepted by a try/catch statement.
62 | Multiple and named arguments are supported with defers.
63 |
65 | You can use the helper sync(fn) and it will use await/defer
66 | automatically.
67 | The helper is non-destructive and the function can still be called asynchronously
68 | if called with a callback.
69 | You can also mix it with other synchronous or asynchronous code.
70 |
72 | Use await/defer manually to get precise control or automatically to write compact and clean code.
73 |
76 | Install it with npm install synchronize.
77 |
80 | The project is hosted on
81 | GitHub.
82 |
83 | You can report bugs and discuss features on the
84 | Issues page.
85 |
Usage patterns
89 |
90 |
103 |
91 |
95 | 92 | data = sync.await(fs.readFile(fname, sync.defer())) 93 |94 |
96 |
102 |
97 | Use await and defer keywords by hand
98 | to call a function synchronously (you can make await and defer global
99 | to make things shorter).
100 |
104 |
121 |
105 |
112 |
106 | sync(fs, 'readFile')
107 |
108 | var data = fs.readFile(fname)
109 | fs.readFile(fname, function(err, data)){}
110 |
111 |
113 |
120 |
114 | Use sync() to make an async function synchronize.js-aware.
115 | You can use it in both ways - synchronous or asynchronous.
116 | Basically it uses the same await/defer pattern, but automatically.
117 | This object form preserves context, unlike the form below.
118 |
122 |
140 |
141 |
142 |
143 |
123 |
132 |
124 | asyncFn = sync(asyncFn)
125 |
126 | var data = asyncFn(input)
127 | // You can still use the async form of this fn
128 | var data = sync.await(asyncFn(input, sync.defer()))
129 | asyncFn(input, function(err, data){})
130 |
131 |
133 |
139 |
134 | You can use sync() on a bare function to return
135 | a synchronized version of the function. It can still be used
136 | in asynchronous form.
137 |
Basic usage, printing content of file
144 | 145 |
146 |
185 |
186 |
147 |
169 |
148 | var sync = require('synchronize')
149 | var fs = require('fs')
150 |
151 | sync(fs, 'readFile')
152 |
153 | sync.fiber(function(){
154 | var data = fs.readFile(__filename, 'utf8')
155 | console.log(data)
156 |
157 | try {
158 | data = fs.readFile('invalid', 'utf8')
159 | } catch (err) {
160 | console.log(err)
161 | }
162 |
163 | fs.readFile(__filename, 'utf8', function(err, data){
164 | console.log(data)
165 | })
166 | })
167 |
168 |
170 |
184 |
171 | In order to use synchronized functions and pause execution without blocking Node.js we
172 | need to wrap execution into a Fiber using sync.fiber().
173 |
175 | Inside of Fiber we can call asynchronous functions as if it's synchronous. 176 |
177 |178 | We can also use standard try/catch statements to catch asynchronous errors. 179 |
180 |181 | Or call readFile asynchronously if we wish. 182 |
183 |Listing and printing files in directory
187 |188 | Listing content of current directory, checking if path is file and printing its content 189 | to console. 190 |
191 |
192 |
242 |
243 |
193 |
213 | Using synchronize
194 |
195 | var sync = require('synchronize')
196 | var fs = require('fs')
197 |
198 | sync(fs, 'readdir', 'stat', 'readFile')
199 |
200 | sync.fiber(function(){
201 | var i, paths, path, stat, data
202 | paths = fs.readdir('.')
203 | for(i = 0; i < paths.length; i++){
204 | path = paths[i]
205 | stat = fs.stat(path)
206 | if(!stat.isFile()) continue
207 | data = fs.readFile(path, 'utf8')
208 | console.log(data)
209 | }
210 | })
211 |
212 |
214 |
241 | The same code without synchronization
215 |
216 | var fs = require('fs')
217 |
218 | var printFile = function(paths, i){
219 | if(i >= paths.length) return
220 | var path = paths[i]
221 | fs.stat(path, function(err, stat){
222 | if(err) throw err
223 | if(stat.isFile()){
224 | fs.readFile(path, 'utf8', function(err, data){
225 | if(err) throw err
226 | console.log(data)
227 | printFile(paths, i + 1)
228 | })
229 | } else {
230 | printFile(paths, i + 1)
231 | }
232 | })
233 | }
234 |
235 | fs.readdir('.', function(err, paths){
236 | if(err) throw err
237 | printFile(paths, 0)
238 | })
239 |
240 | Parallel and serial operations
244 |
245 | Synchronize.js can run multiple operations in parallel using
246 | sync.parallel().
247 |
249 |
298 |
299 |
250 |
273 | Async operations in serial
251 |
252 | var sync = require('synchronize')
253 |
254 | var read = function(a, cb) {
255 | setTimeout(function(){
256 | // remember that callbacks expect (err, result)
257 | cb(null, a)
258 | }, 1000)
259 | }
260 |
261 | // We can use the `sync` helper here to avoid using
262 | // `await()` and `defer()` manually.
263 | read = sync(read);
264 |
265 | sync.fiber(function() {
266 | var results = []
267 | results.push(read(1)))
268 | results.push(read(2)))
269 | // results now contains [1,2]
270 | })
271 |
272 |
274 |
297 | Async operations in parallel
275 |
276 | var sync = require('synchronize')
277 |
278 | function read(a, cb) {
279 | setTimeout(function(){
280 | cb(null, a)
281 | }, 1000)
282 | }
283 |
284 | // Runs in parallel
285 | sync.fiber(function() {
286 | sync.parallel(function() {
287 | // You must call defer() manually within
288 | // a parallel operation.
289 | read(1, sync.defer())
290 | read(2, sync.defer())
291 | });
292 | var results = sync.await()
293 | // results now contains [1,2]
294 | });
295 |
296 | Multiple arguments in callbacks
300 |
301 | Synchronize.js accepts multiple arguments in callbacks using sync.defers().
302 |
304 |
349 |
350 |
351 |
305 |
325 | Multiple arguments in serial
306 |
307 | var sync = require('synchronize')
308 |
309 | function read(a, b, c, cb) {
310 | setTimeout(function(){
311 | cb(null, a, b, c)
312 | }, 1000)
313 | }
314 |
315 | sync.fiber(function() {
316 | // Returns [1,2,3]
317 | var results = sync.await(
318 | read(1, 2, 3, sync.defers()))
319 | // Returns {a: 4, b: 5, c: 6}
320 | var namedResults = sync.await(
321 | read(4, 5, 6, sync.defers('a', 'b', 'c')))
322 | })
323 |
324 |
326 |
348 | Multiple arguments in parallel
327 |
328 | var sync = require('synchronize')
329 |
330 | function read(a, b, c, cb) {
331 | setTimeout(function(){
332 | cb(null, a, b, c)
333 | }, 1000)
334 | }
335 |
336 | sync.fiber(function() {
337 | sync.parallel(function(){
338 | read(1, 2, 3, sync.defers())
339 | read(4, 5, 6, sync.defers())
340 | });
341 | // returns [[1,2,3],[4,5,6]]
342 | var results = sync.await()
343 | // concat to get [1,2,3,4,5,6]
344 | results = [].concat.apply([], results)
345 | })
346 |
347 | Usage with Express.js
352 |
353 |
380 |
381 |
354 |
374 |
355 | var sync = require('synchronize')
356 | var fs = require('fs')
357 | var express = require('express')
358 |
359 | sync(fs, 'readFile')
360 |
361 | var app = express.createServer()
362 | app.use(function(req, res, next){
363 | sync.fiber(next)
364 | })
365 |
366 | app.get('/', function(req, res){
367 | var data = fs.readFile(__filename, 'utf8')
368 | res.send(data, {'Content-Type': 'text/plain'})
369 | })
370 |
371 | app.listen(3000)
372 |
373 |
375 |
379 | Synchronized code can be mixed with asynchronous code in any combination.
376 |377 | Here is one possible way to use it with Express.js.
378 |Usage with Mocha.js
382 |
383 |
413 |
414 |
415 |
384 |
399 |
385 | var sync = require('synchronize')
386 | var fs = require('fs')
387 |
388 | sync(fs, 'readFile')
389 |
390 | var async = sync.asyncIt
391 |
392 | describe('File System', function(){
393 | it('should read file', async(function(){
394 | var data = fs.readFile(__filename, 'utf8')
395 | }))
396 | })
397 |
398 |
400 |
412 |
401 | You can use the sync.asyncIt helper to greatly simplify writing
402 | asynchronous tests.
403 |
406 | You may also take a look at 407 | 408 | this real-life test scenario 409 | that uses synchronize to simplify asynchronous calls for MongoDB. 410 |
411 |Similar tools
416 |417 | MonoJS - synchronous web framework based on synchronize. 418 |
419 | 420 |421 | 422 |
Copyright Alexey Petrushin, released under MIT License
423 |
429 |
430 |
431 |
432 |
433 |
434 |
437 |
438 |
439 |
--------------------------------------------------------------------------------
/examples/basic.js:
--------------------------------------------------------------------------------
1 | var sync = require('synchronize')
2 | var fs = require('fs')
3 |
4 | sync(fs, 'readFile')
5 |
6 | sync.fiber(function(){
7 | var data = fs.readFile(__filename, 'utf8')
8 | console.log(data)
9 |
10 | try {
11 | data = fs.readFile('invalid', 'utf8')
12 | } catch (err) {
13 | console.log(err)
14 | }
15 |
16 | fs.readFile(__filename, 'utf8', function(err, data){
17 | console.log(data)
18 | })
19 | })
--------------------------------------------------------------------------------
/examples/express.js:
--------------------------------------------------------------------------------
1 | var sync = require('synchronize')
2 | var fs = require('fs')
3 | var express = require('express')
4 |
5 | sync(fs, 'readFile')
6 |
7 | var app = express.createServer()
8 | app.use(function(req, res, next){
9 | sync.fiber(next)
10 | })
11 |
12 | app.get('/', function(req, res){
13 | var data = fs.readFile(__filename, 'utf8')
14 | res.send(data, {'Content-Type': 'text/plain'})
15 | })
16 |
17 | app.listen(3000)
--------------------------------------------------------------------------------
/examples/list.js:
--------------------------------------------------------------------------------
1 | var sync = require('synchronize')
2 | var fs = require('fs')
3 |
4 | sync(fs, 'readdir', 'stat', 'readFile')
5 |
6 | sync.fiber(function(){
7 | var i, paths, path, stat, data
8 | paths = fs.readdir('.')
9 | for(i = 0; i < paths.length; i++){
10 | path = paths[i]
11 | stat = fs.stat(path)
12 | if(!stat.isFile()) continue
13 | data = fs.readFile(path, 'utf8')
14 | console.log(data)
15 | }
16 | })
--------------------------------------------------------------------------------
/examples/listAsync.js:
--------------------------------------------------------------------------------
1 | var fs = require('fs')
2 |
3 | var printFile = function(paths, i){
4 | if(i >= paths.length) return
5 | var path = paths[i]
6 | fs.stat(path, function(err, stat){
7 | if(err) throw err
8 | if(stat.isFile()){
9 | fs.readFile(path, 'utf8', function(err, data){
10 | if(err) throw err
11 | console.log(data)
12 | printFile(paths, i + 1)
13 | })
14 | } else {
15 | printFile(paths, i + 1)
16 | }
17 | })
18 | }
19 |
20 | fs.readdir('.', function(err, paths){
21 | if(err) throw err
22 | printFile(paths, 0)
23 | })
--------------------------------------------------------------------------------
/examples/mocha.js:
--------------------------------------------------------------------------------
1 | var sync = require('synchronize')
2 | var fs = require('fs')
3 |
4 | sync(fs, 'readFile')
5 |
6 | var async = sync.asyncIt
7 |
8 | describe('File System', function(){
9 | it('should read file', async(function(){
10 | var data = fs.readFile(__filename, 'utf8')
11 | }))
12 | })
--------------------------------------------------------------------------------
/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 | Please follow this link.
7 | 8 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "synchronize", 3 | "main": "./sync", 4 | "version": "2.0.1", 5 | "homepage": "http://alexeypetrushin.github.com/synchronize", 6 | "repository": { 7 | "type": "git", 8 | "url": "https://github.com/alexeypetrushin/synchronize.git" 9 | }, 10 | "dependencies": { 11 | "fibers": "^3.0.0" 12 | }, 13 | "devDependencies": { 14 | "mocha": "1.0.x", 15 | "chai": "1.3.x" 16 | }, 17 | "scripts": { 18 | "test": "mocha -R spec test/*.js" 19 | }, 20 | "description": "Turns asynchronous function into synchronous", 21 | "keywords": [ 22 | "Fibers", 23 | "Sync", 24 | "Async", 25 | "Control Flow" 26 | ], 27 | "author": { 28 | "name": "Alexey Petrushin", 29 | "url": "http://petrush.in" 30 | }, 31 | "license": "MIT" 32 | } 33 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | synchronize.js allows You write asynchronous code as if it's synchronous. 2 | 3 | Documentation [http://alexeypetrushin.github.com/synchronize](http://alexeypetrushin.github.com/synchronize) 4 | 5 | Installation `npm install synchronize` 6 | 7 | [](https://travis-ci.org/alexeypetrushin/synchronize) 8 | 9 | Contributors: 10 | 11 | - [Alexey Petrushin](https://github.com/alexeypetrushin) 12 | - [d3m3vilurr](https://github.com/d3m3vilurr) 13 | - [James Manning](https://github.com/jamesmanning) 14 | - [ssafejava](https://github.com/ssafejava) 15 | - [Brad Vogel](https://github.com/bradvogel) 16 | - [grassick](https://github.com/grassick) 17 | - [Andrew Tamura](https://github.com/andrewtamura) 18 | - [Jeff Wear](https://github.com/wearhere) 19 | 20 | Other resources: 21 | 22 | - [Patterns and anti-patterns using synchronize.js](https://mixmax.com/blog/node-fibers-using-synchronize-js) 23 | - [synchronize-helpers: This module provides helpers for wrapping sync.defer() for synchronize.js](https://github.com/mixmaxhq/synchronize-helpers) 24 | - [synchronize-iterate: Native iteration over cursor-like objects with synchronize.js](https://github.com/mixmaxhq/synchronize-iterate) 25 | - [synchronize-pool: Concurrent control of fibers on a per-pool basis with synchronize.js](https://github.com/mixmaxhq/synchronize-pool) 26 | - [synchronize-bdd: A small synchronize.js wrapper around the BDD block functions from Mocha and Jasmine](https://github.com/mixmaxhq/synchronize-bdd) 27 | 28 | Copyright (c) Alexey Petrushin, http://alex-craft.com, released under the MIT license. 29 | -------------------------------------------------------------------------------- /sync.js: -------------------------------------------------------------------------------- 1 | /*jshint node: true, indent:2, loopfunc: true, asi: true, undef:true*/ 2 | 3 | var Fiber = require('fibers') 4 | 5 | // Takes function and returns its synchronized version, it's still backward compatible and 6 | // can be used as asynchronous `syncFn = sync(asyncFn)`. 7 | // 8 | // Or You can provide object and it will synchronize its functions `sync(obj, fname1, fname2, ...)`. 9 | // 10 | // New synchronized version of function is backward compatible and You may call it as usual with 11 | // explicit callback or inside of `fiber` with `aware` and `defer` keywords. 12 | var sync = module.exports = function(){ 13 | if(arguments.length > 1){ 14 | // Synchronizing functions of object. 15 | var obj = arguments[0] 16 | for(var i = 1; i < arguments.length; i++){ 17 | var fname = arguments[i] 18 | var fn = obj[fname] 19 | if(!fn) throw new Error("object doesn't have '" + fname + "' function!") 20 | obj[fname] = sync(fn) 21 | } 22 | }else{ 23 | return sync.syncFn(arguments[0]) 24 | } 25 | } 26 | 27 | var nextTick = global.setImmediate || process.nextTick || function(cb) { setTimeout(cb, 0) } 28 | 29 | // Sometimes `Fiber` needed outside of `sync`. 30 | sync.Fiber = Fiber 31 | 32 | // Takes function and returns its synchronized version, it's still backward compatible and can 33 | // be used as asynchronous. 34 | sync.syncFn = function(fn){ 35 | // Preventing function to be synchronized twice. 36 | if(fn._synchronized) return fn 37 | 38 | var syncFn = function(){ 39 | // Using fibers only if there's active fiber and callback not provided explicitly. 40 | if(Fiber.current && (typeof arguments[arguments.length-1] !== 'function')){ 41 | // Calling asynchronous function with our special fiber-aware callback. 42 | Array.prototype.push.call(arguments, sync.defer()) 43 | fn.apply(this, arguments) 44 | 45 | // Waiting for asynchronous result. 46 | return sync.await() 47 | }else{ 48 | // If there's no active fiber or callback provided explicitly we call original version. 49 | return fn.apply(this, arguments) 50 | } 51 | } 52 | 53 | // Marking function as synchronized. 54 | syncFn._synchronized = true 55 | 56 | return syncFn 57 | } 58 | // Use it to wait for asynchronous callback. 59 | sync.await = Fiber.yield 60 | 61 | // Creates fiber-aware asynchronous callback resuming current fiber when it will be finished. 62 | sync.defer = function(){ 63 | if(!Fiber.current) throw new Error("no current Fiber, defer can't be used without Fiber!") 64 | if(Fiber.current._syncParallel) return sync.deferParallel() 65 | else return sync.deferSerial() 66 | } 67 | 68 | // Exactly the same as defer, but additionally it triggers an error if there's no response 69 | // on time. 70 | sync.deferWithTimeout = function(timeout, message){ 71 | if(!Fiber.current) throw new Error("no current Fiber, deferWithTimeout can't be used without Fiber!") 72 | if(!timeout) throw new Error("no timeout provided!") 73 | if(Fiber.current._syncParallel) throw new Error("deferWithTimeout can't be used in parallel!") 74 | 75 | var defer = this.defer() 76 | var error = new Error(message || "defer timed out!") 77 | var called = false 78 | var d = setTimeout(function(){ 79 | if(called) return 80 | called = true 81 | defer(error) 82 | }, timeout) 83 | 84 | return function(){ 85 | if(called) return 86 | called = true 87 | clearTimeout(d) 88 | return defer.apply(this, arguments) 89 | } 90 | } 91 | 92 | // 93 | sync.deferSerial = function(){ 94 | var fiber = Fiber.current 95 | if(!fiber) throw new Error("no current Fiber, defer can't be used without Fiber!") 96 | // if(fiber._defered) throw new Error("invalid usage, should be clear previous defer!") 97 | // fiber._defered = true 98 | // Prevent recursive call 99 | var called = false 100 | // Returning asynchronous callback. 101 | return function(err, result){ 102 | if (called) throw new Error("defer can't be used twice!") 103 | called = true 104 | 105 | // Wrapping in nextTick as a safe measure against not asynchronous usage. 106 | nextTick(function(){ 107 | // fiber._defered = false 108 | if(fiber._syncIsTerminated) return 109 | if(err){ 110 | // Resuming fiber and throwing error. 111 | fiber.throwInto(err) 112 | }else{ 113 | // Resuming fiber and returning result. 114 | fiber.run(result) 115 | } 116 | }) 117 | } 118 | } 119 | 120 | sync.deferParallel = function(){ 121 | var fiber = Fiber.current 122 | if(!fiber) throw new Error("no current Fiber, defer can't be used without Fiber!") 123 | if(!fiber._syncParallel) throw new Error("invalid usage, should be called in parallel mode!") 124 | var data = fiber._syncParallel 125 | 126 | // Counting amount of `defer` calls. 127 | data.called += 1 128 | var resultIndex = data.called - 1 129 | 130 | // Returning asynchronous callback. 131 | return function(err, result){ 132 | // Wrapping in nextTick as a safe measure against not asynchronous usage. 133 | nextTick(function(){ 134 | if(fiber._syncIsTerminated) return 135 | // Error in any of parallel call will result in aborting all of the calls. 136 | if(data.errorHasBeenThrown) return 137 | if(err){ 138 | data.errorHasBeenThrown = true 139 | // Resuming fiber and throwing error. 140 | fiber.throwInto(err) 141 | }else{ 142 | data.returned += 1 143 | data.results[resultIndex] = result 144 | // Resuming fiber and returning result when all callbacks finished. 145 | if(data.returned == data.called) fiber.run(data.results) 146 | } 147 | }) 148 | } 149 | } 150 | 151 | sync.defers = function(){ 152 | if(!Fiber.current) throw new Error("no current Fiber, defer can't be used without Fiber!") 153 | if(Fiber.current._syncParallel) return sync.defersParallel.apply(sync, arguments) 154 | else return sync.defersSerial.apply(sync, arguments) 155 | } 156 | 157 | sync.defersSerial = function(){ 158 | var fiber = Fiber.current; 159 | if(!fiber) throw new Error("no current Fiber, defer can't be used without Fiber!") 160 | // if(fiber._defered) throw new Error("invalid usage, should be clear previous defer!") 161 | // fiber._defered = true 162 | 163 | var kwds = Array.prototype.slice.call(arguments) 164 | 165 | // Prevent recursive call 166 | var called = false 167 | // Returning asynchronous callback. 168 | return function(err) { 169 | if (called) throw new Error("defer can't be used twice!") 170 | called = true 171 | // Wrapping in nextTick as a safe measure against not asynchronous usage. 172 | var args = Array.prototype.slice.call(arguments, 1) 173 | nextTick(function(){ 174 | // fiber._defered = false 175 | if(fiber._syncIsTerminated) return 176 | if (err) { 177 | // Resuming fiber and throwing error. 178 | fiber.throwInto(err) 179 | } else { 180 | var results; 181 | if(!kwds.length){ 182 | results = args 183 | } else { 184 | results = {} 185 | kwds.forEach(function(kwd, i){ 186 | results[kwd]=args[i] 187 | }) 188 | } 189 | fiber.run(results) 190 | } 191 | }) 192 | } 193 | } 194 | 195 | sync.defersParallel = function(){ 196 | var fiber = Fiber.current 197 | if(!fiber) throw new Error("no current Fiber, defer can't be used without Fiber!") 198 | if(!fiber._syncParallel) throw new Error("invalid usage, should be called in parallel mode!") 199 | var data = fiber._syncParallel 200 | // Counting amount of `defer` calls. 201 | data.called += 1 202 | var resultIndex = data.called - 1 203 | 204 | var kwds = Array.prototype.slice.call(arguments) 205 | // Returning asynchronous callback. 206 | return function(err) { 207 | // Wrapping in nextTick as a safe measure against not asynchronous usage. 208 | var args = Array.prototype.slice.call(arguments, 1) 209 | nextTick(function(){ 210 | if(fiber._syncIsTerminated) return 211 | 212 | // Error in any of parallel call will result in aborting all of the calls. 213 | if(data.errorHasBeenThrown) return 214 | if (err) { 215 | data.errorHasBeenThrown = true 216 | // Resuming fiber and throwing error. 217 | fiber.throwInto(err) 218 | } 219 | var results; 220 | if(!kwds.length){ 221 | results = args 222 | } else { 223 | results = {} 224 | kwds.forEach(function(kwd, i){ 225 | results[kwd]=args[i] 226 | }) 227 | } 228 | data.returned += 1 229 | data.results[resultIndex] = results 230 | if(data.returned == data.called) fiber.run(data.results) 231 | }) 232 | } 233 | } 234 | 235 | // Support for parallel calls, all `defer` calls within callback will be 236 | // performed in parallel. 237 | sync.parallel = function(cb){ 238 | var fiber = Fiber.current 239 | if(!fiber) throw new Error("no current Fiber, defer can't be used without Fiber!") 240 | 241 | // Enabling `defer` calls to be performed in parallel. 242 | // There's an important note - error in any parallel call will result in aborting 243 | // all of the parallel calls. 244 | fiber._syncParallel = {called: 0, returned: 0, results: [], errorHasBeenThrown: false} 245 | try{ 246 | cb.call(this) 247 | }finally{ 248 | // If neither `defer` nor `defers` were called within the callback, we need 249 | // to run the fiber ourselves or else the fiber will unwind when `await` is called. 250 | // This might happen if the user intended to enumerate an array within the 251 | // callback, calling `defer` once per array item, but the array was empty. 252 | if (!fiber._syncParallel.called) { 253 | nextTick(function(){ 254 | // Return an empty array to represent that there were no results. 255 | if(!fiber._syncIsTerminated) fiber.run([]) 256 | }) 257 | } 258 | delete fiber._syncParallel 259 | } 260 | } 261 | 262 | function decorateError(error, callStack){ 263 | if (typeof error === 'object') { 264 | var errorStack = error.stack; 265 | Object.defineProperties(error, { 266 | stack: { 267 | configurable: true, 268 | get: function () { 269 | if (!callStack) { 270 | return errorStack; 271 | } 272 | return [errorStack, callStack.substring(callStack.indexOf('\n') + 1)].join('\n') 273 | } 274 | } 275 | }); 276 | } 277 | return error; 278 | } 279 | 280 | // Executes `cb` within `Fiber`, when it finish it will call `done` callback. 281 | // If error will be thrown during execution, this error will be catched and passed to `done`, 282 | // if `done` not provided it will be just rethrown. 283 | sync.fiber = function(cb, done){ 284 | var that = this 285 | var fiber = Fiber(function(){ 286 | // Prevent restart fiber 287 | if (Fiber.current._started) return 288 | if (done) { 289 | var result 290 | try { 291 | result = cb.call(that) 292 | Fiber.current._syncIsTerminated = true 293 | } catch (error) { 294 | return done(decorateError(error, Fiber.current._callStack.stack)) 295 | } 296 | done(null, result) 297 | } else { 298 | // Don't catch errors if done not provided! 299 | cb.call(that) 300 | Fiber.current._syncIsTerminated = true 301 | } 302 | }) 303 | if (done) { 304 | fiber._callStack = {} 305 | Error.captureStackTrace(fiber._callStack, this.fiber) 306 | } 307 | fiber.run() 308 | fiber._started = true 309 | } 310 | 311 | // Asynchronous wrapper for mocha.js tests. 312 | // 313 | // async = sync.asyncIt 314 | // it('should pass', async(function(){ 315 | // ... 316 | // })) 317 | // 318 | sync.asyncIt = function(cb){ 319 | if(!cb) throw "no callback for async spec helper!" 320 | return function(done){sync.fiber(cb.bind(this), done)} 321 | } 322 | 323 | // Same as `sync` but with verbose logging for every method invocation. 324 | // Ignore this method, it shouldn't be used unless you want to track down 325 | // tricky and complex bugs and need full information abouth how and when all 326 | // this async stuff has been called. 327 | var fiberIdCounter = 1 328 | sync.syncWithDebug = function(){ 329 | if(arguments.length > 1){ 330 | // Synchronizing functions of object. 331 | var obj = arguments[0] 332 | for(var i = 1; i < arguments.length; i++){ 333 | (function(fname){ 334 | var fn = obj[fname] 335 | if(!fn) throw new Error("object doesn't have '" + fname + "' function!") 336 | var syncedFn = sync(fn) 337 | obj[fname] = function(){ 338 | if(Fiber.current && Fiber.current._fiberId === undefined){ 339 | Fiber.current._fiberId = fiberIdCounter 340 | fiberIdCounter = fiberIdCounter + 1 341 | Fiber.current._callbackLevel = 0 342 | } 343 | 344 | var fiberId = '-' 345 | if(Fiber.current){ 346 | fiberId = Fiber.current._fiberId 347 | Fiber.current._callbackLevel = Fiber.current._callbackLevel + 1 348 | } 349 | 350 | var indent = ' ' 351 | if(Fiber.current) 352 | for(var j = 0; j < Fiber.current._callbackLevel; j++) indent = indent + ' ' 353 | 354 | console.log(fiberId + indent + this.constructor.name + '.' + 355 | fname + " called", JSON.stringify(arguments)) 356 | 357 | var result 358 | try{ 359 | result = syncedFn.apply(this, arguments) 360 | }finally{ 361 | console.log(fiberId + indent + this.constructor.name + '.' + 362 | fname + " finished") 363 | 364 | if(Fiber.current) 365 | Fiber.current._callbackLevel = Fiber.current._callbackLevel - 1 366 | } 367 | return result 368 | } 369 | })(arguments[i]) 370 | } 371 | }else{ 372 | return sync.syncFn(arguments[0]) 373 | } 374 | } 375 | -------------------------------------------------------------------------------- /test/sync.js: -------------------------------------------------------------------------------- 1 | /*jshint node: true, indent:2, loopfunc: true, asi: true, undef:true, mocha: true */ 2 | 3 | // require('longjohn') 4 | 5 | var sync = require('../sync') 6 | var Fiber = require('fibers') 7 | var expect = require('chai').expect 8 | 9 | describe('Control Flow', function(){ 10 | var waitAndReturn = function(time, err, value, cb){ 11 | setTimeout(function(){cb(err, value)}, time) 12 | } 13 | 14 | var fn = function(arg, cb){ 15 | expect(arg).to.eql('something') 16 | process.nextTick(function(){ 17 | cb(null, 'ok') 18 | }) 19 | } 20 | 21 | it('should provide await & defer', function(done){ 22 | sync.fiber(function(){ 23 | var result = sync.await(fn('something', sync.defer())) 24 | expect(result).to.eql('ok') 25 | }, done) 26 | }) 27 | 28 | it('should synchronize function', function(done){ 29 | fn = sync(fn) 30 | sync.fiber(function(){ 31 | expect(fn('something')).to.eql('ok') 32 | }, done) 33 | }) 34 | 35 | it('should be save aginst synchronizing function twice', function(done){ 36 | fn = sync(sync(fn)) 37 | sync.fiber(function(){ 38 | expect(fn('something')).to.eql('ok') 39 | }, done) 40 | }) 41 | 42 | it('should allow call synchronized function explicitly', function(done){ 43 | fn = sync(fn) 44 | fn('something', function(err, result){ 45 | expect(result).to.eql('ok') 46 | done(err) 47 | }) 48 | }) 49 | 50 | it("should catch asynchronous errors", function(done){ 51 | var fn = function(cb){ 52 | process.nextTick(function(){ 53 | cb(new Error('an error')) 54 | }) 55 | } 56 | fn = sync(fn) 57 | sync.fiber(function(){ 58 | var err 59 | try { 60 | fn() 61 | } catch (e) { 62 | err = e 63 | } 64 | expect(err.message).to.eql('an error') 65 | }, done) 66 | }) 67 | 68 | it("should be compatible with not asynchronous cbs", function(done){ 69 | fn = function(cb){ 70 | cb(null, 'ok') 71 | } 72 | fn = sync(fn) 73 | sync.fiber(function(){ 74 | expect(fn()).to.eql('ok') 75 | }, done) 76 | }) 77 | 78 | it("should catch non asynchronous errors", function(done){ 79 | fn = function(cb){ 80 | cb(new Error('an error')) 81 | } 82 | fn = sync(fn) 83 | sync.fiber(function(){ 84 | var err 85 | try { 86 | fn() 87 | } catch (e) { 88 | err = e 89 | } 90 | expect(err.message).to.eql('an error') 91 | }, done) 92 | }) 93 | 94 | describe("Special cases", function(){ 95 | it('should be able to emulate sleep', function(done){ 96 | var sleep = function(ms){ 97 | sync.await(setTimeout(sync.defer(), ms)) 98 | } 99 | 100 | sync.fiber(function(){ 101 | var start = new Date().getTime() 102 | sleep(50) 103 | expect(new Date().getTime()).to.be.greaterThan(start) 104 | }, done) 105 | }) 106 | }) 107 | 108 | it('should support parallel calls', function(done){ 109 | sync.fiber(function(){ 110 | var calls = [] 111 | var readA = function(cb){ 112 | calls.push('readA') 113 | process.nextTick(function(){ 114 | calls.push('nextTick') 115 | cb(null, 'dataA') 116 | }) 117 | } 118 | var readB = function(cb){ 119 | calls.push('readB') 120 | process.nextTick(function(){ 121 | calls.push('nextTick') 122 | cb(null, 'dataB') 123 | }) 124 | } 125 | 126 | sync.parallel(function(){ 127 | readA(sync.defer()) 128 | readB(sync.defer()) 129 | }) 130 | var results = sync.await() 131 | 132 | expect(results).to.eql(['dataA', 'dataB']) 133 | expect(calls).to.eql(['readA', 'readB', 'nextTick', 'nextTick']) 134 | }, done) 135 | }) 136 | 137 | it('should support multiple arguments', function(done){ 138 | sync.fiber(function(){ 139 | var read = function(cb){ 140 | process.nextTick(function(){ 141 | cb(null, 'data1', 'data2') 142 | }) 143 | } 144 | 145 | var result = sync.await(read(sync.defers())) 146 | expect(result).to.eql(['data1', 'data2']) 147 | }, done) 148 | }) 149 | 150 | it('should support multiple `named` arguments', function(done){ 151 | sync.fiber(function(){ 152 | var read = function(cb){ 153 | process.nextTick(function(){ 154 | cb(null, 'data1', 'data2') 155 | }) 156 | } 157 | 158 | var result = sync.await(read(sync.defers('a', 'b'))) 159 | expect(result).to.eql({a: 'data1', b: 'data2'}) 160 | }, done) 161 | }) 162 | 163 | it('should support multiple arguments parallel calls', function(done){ 164 | sync.fiber(function(){ 165 | var read = function(cb){ 166 | process.nextTick(function(){ 167 | cb(null, 'data1', 'data2') 168 | }) 169 | } 170 | 171 | sync.parallel(function(){ 172 | read(sync.defers()) 173 | read(sync.defers('a', 'b')) 174 | }) 175 | var results = sync.await() 176 | expect(results).to.eql([['data1', 'data2'], {a: 'data1', b: 'data2'}]) 177 | }, done) 178 | }) 179 | 180 | it('should fiber call just once at raise error', function(done){ 181 | var read = function(cb){ 182 | process.nextTick(function(){ 183 | cb(new Error('an error')) 184 | }) 185 | } 186 | 187 | var called = 0 188 | sync.fiber(function(){ 189 | called += 1 190 | sync.await(read(sync.defers())) 191 | }, function() {}) 192 | 193 | setTimeout(function(){ 194 | expect(called).to.eql(1) 195 | done() 196 | }, 100) 197 | }) 198 | 199 | it('should handle parallel errors', function(done){ 200 | sync.fiber(function(){ 201 | var calls = [] 202 | var readA = function(cb){ 203 | process.nextTick(function(){ 204 | cb(new Error("error a")) 205 | }) 206 | } 207 | var readB = function(cb){ 208 | process.nextTick(function(){ 209 | cb(new Error("error b")) 210 | }) 211 | } 212 | 213 | try { 214 | sync.parallel(function(){ 215 | readA(sync.defer()) 216 | readB(sync.defer()) 217 | }) 218 | var results = sync.await() 219 | }catch(err){ 220 | if(err.message == 'error a') expect(err.message).to.eql('error a') 221 | else expect(err.message).to.eql('error b') 222 | } 223 | }, done) 224 | }) 225 | 226 | it('should handle parallel errors with multiple arguments', function(done){ 227 | sync.fiber(function(){ 228 | var calls = [] 229 | var readA = function(cb){ 230 | process.nextTick(function(){ 231 | cb(new Error("error a")) 232 | }) 233 | } 234 | var readB = function(cb){ 235 | process.nextTick(function(){ 236 | cb(new Error("error b")) 237 | }) 238 | } 239 | 240 | try { 241 | sync.parallel(function(){ 242 | readA(sync.defers()) 243 | readB(sync.defers()) 244 | }) 245 | var results = sync.await() 246 | }catch(err){ 247 | if(err.message == 'error a') expect(err.message).to.eql('error a') 248 | else expect(err.message).to.eql('error b') 249 | } 250 | }, done) 251 | }) 252 | 253 | it('should not unwind when await is called after an empty parallel block', function(done){ 254 | sync.fiber(function(){ 255 | sync.parallel(function(){ 256 | // Imagine that the user intends to enumerate an array here, calling 257 | // `defer` once per array item, but the array is empty. 258 | }) 259 | expect(sync.await()).to.eql([]) 260 | }, done) 261 | }) 262 | 263 | it('should return result from fiber', function(done){ 264 | sync.fiber(function(){ 265 | return 'some value' 266 | }, function(err, result){ 267 | expect(err).to.eql(null) 268 | expect(result).to.eql('some value') 269 | done() 270 | }) 271 | }) 272 | 273 | it('should abort on timeout', function(done){ 274 | sync.fiber(function(){ 275 | waitAndReturn(10, null, 'some result', sync.deferWithTimeout(100)) 276 | expect(sync.await()).to.eql('some result') 277 | 278 | try{ 279 | waitAndReturn(10, null, 'some result', sync.deferWithTimeout(1)) 280 | expect(sync.await()).to.eql('some result') 281 | }catch(err){ 282 | expect(err.message).to.eql('defer timed out!') 283 | } 284 | }, done) 285 | }) 286 | 287 | // TODO, add also the same specs for `defers`. 288 | it('should not resume terminated fiber with value', function(done){ 289 | var runCount = 0 290 | var results = [] 291 | sync.fiber(function(){ 292 | runCount += 1 293 | waitAndReturn(1, null, 'some value', sync.defer()) 294 | }, function(err){ 295 | results.push(err || null) 296 | }) 297 | 298 | // Need to wait for some time after the fiber ends its execution to make sure 299 | // it won't be runned one more time. 300 | setTimeout(function(){ 301 | expect(runCount).to.eql(1) 302 | expect(results.length).to.eql(1) 303 | expect(results[0]).to.eql(null) 304 | done() 305 | }, 10) 306 | }) 307 | 308 | // TODO, add also the same specs for `defers`. 309 | it('should not resume terminated fiber with error', function(done){ 310 | var runCount = 0 311 | var results = [] 312 | sync.fiber(function(){ 313 | runCount += 1 314 | waitAndReturn(1, (new Error('some error')), null, sync.defer()) 315 | }, function(err){ 316 | results.push(err) 317 | }) 318 | 319 | // Need to wait for some time after the fiber ends its execution to make sure 320 | // it won't be runned one more time. 321 | setTimeout(function(){ 322 | expect(runCount).to.eql(1) 323 | expect(results.length).to.eql(1) 324 | expect(results[0]).to.eql(null) 325 | done() 326 | }, 10) 327 | }) 328 | 329 | it('should call terminate callback just once', function(done) { 330 | var callCount = 0 331 | var callback = function(error) { 332 | callCount += 1 333 | throw new Error('some error') 334 | } 335 | expect(function() {sync.fiber(function() {}, callback)}).to.throw(Error) 336 | setTimeout(function() { 337 | expect(callCount).to.eql(1) 338 | done() 339 | }, 10) 340 | }) 341 | 342 | it('should throw error if defer called twice', function(done){ 343 | sync.fiber(function(){ 344 | var defer = sync.defer() 345 | defer() 346 | sync.await() 347 | expect(defer).to.throw(Error) 348 | }, done) 349 | }) 350 | 351 | it('should call defer only once in the fiber process', function(done){ 352 | var broken = function(cb) { 353 | sync.fiber(function() { 354 | cb() 355 | }, cb) 356 | } 357 | sync.fiber(function(){ 358 | broken(sync.defer()) 359 | sync.await() 360 | throw new Error('an error') 361 | }, function(err) { 362 | expect(err).to.exist 363 | expect(err.message).to.eql("defer can't be used twice!") 364 | done() 365 | }) 366 | }) 367 | 368 | it('should throw error if defers called twice', function(done){ 369 | sync.fiber(function(){ 370 | var defer = sync.defers() 371 | defer() 372 | sync.await() 373 | expect(defer).to.throw(Error) 374 | }, done) 375 | }) 376 | 377 | it('should prevent defers call just once in fiber process', function(done){ 378 | var broken = function(cb) { 379 | sync.fiber(function() { 380 | cb() 381 | }, cb) 382 | } 383 | sync.fiber(function(){ 384 | broken(sync.defers()) 385 | sync.await() 386 | throw new Error('an error') 387 | }, function(err) { 388 | expect(err).to.exist 389 | expect(err.message).to.eql("defer can't be used twice!") 390 | done() 391 | }) 392 | }) 393 | 394 | it('should prevent restart fiber', function(done){ 395 | var currentFiber 396 | var called = 0 397 | sync.fiber(function(){ 398 | called += 1 399 | currentFiber = sync.Fiber.current 400 | }) 401 | setTimeout(function() { 402 | currentFiber.run() 403 | }, 1) 404 | setTimeout(function() { 405 | expect(called).to.eql(1) 406 | done() 407 | }, 10) 408 | }) 409 | 410 | it('should throw error when not matched defer-await pair', function(done){ 411 | sync.fiber(function(){ 412 | process.nextTick(sync.defer()) 413 | expect(function() { process.nextTick(sync.defer()) }).to.throw(Error) 414 | sync.await() 415 | process.nextTick(sync.defers()) 416 | expect(function() { process.nextTick(sync.defers()) }).to.throw(Error) 417 | sync.await() 418 | }, done) 419 | }) 420 | 421 | it('should have full error stack', function(done) { 422 | var raise = function(cb) { 423 | setTimeout(function() { 424 | cb(new Error('some')) 425 | }, 1) 426 | } 427 | var re = /.* \(.*\/test\/sync.js:([0-9]+):([0-9]+)\)/ 428 | var s1 = new Error().stack.split('\n')[1] 429 | var exp = parseInt(re.exec(s1)[1], 10) 430 | sync.fiber(function() { 431 | raise(sync.defer()) 432 | sync.await() 433 | }, function(err) { 434 | expect(err).to.exist 435 | var line 436 | if (err.stack.split('\n').slice(2).some(function(l) { 437 | var m = re.exec(l) 438 | if (!m) { 439 | return 440 | } 441 | line = parseInt(m[1], 10) 442 | return true 443 | })) 444 | expect(line).to.eql(exp + 2) 445 | done() 446 | }) 447 | }) 448 | 449 | beforeEach(function(){ 450 | this.someKey = 'some value' 451 | }) 452 | it('should provide asyncIt helper for tests', sync.asyncIt(function(){ 453 | expect(Fiber.current).to.exist 454 | expect(this.someKey).to.eql('some value') 455 | })) 456 | }) 457 | --------------------------------------------------------------------------------