Permalink
Browse files

Merge branch 'master' of github.com:anodejs/node-ypatterns

  • Loading branch information...
2 parents a1a68a7 + 02892a3 commit e39b04534a0b1a0e8c359bc8db0fa36f26403387 @yosefd yosefd committed Mar 13, 2012
Showing with 113 additions and 2 deletions.
  1. +113 −2 README.md
View
@@ -1,9 +1,120 @@
# ypatterns
+Miscellaneous programming patterns.
+
[![Build Status](https://secure.travis-ci.org/anodejs/node-ypatterns.png)](http://travis-ci.org/anodejs/node-ypatterns)
-Experimental version.
-Usage manual will be published with the next version.
+## Gate
+
+This is the pattern of usage counter.
+Anybody can enter the gate is the gate is not closed.
+When gate is closed, nobody allowed entering. However, all those that are already inside, can exit the gate.
+The completion of gate closure will be called when everybody left (exited the gate).
+
+### Usage
+
+```javascript
+var gate = require('ypatterns').gate;
+//...
+if (gate.enter()) {
+ //... entrance granted.
+ //...
+ gate.exit();
+}
+else {
+ //... entrance is not allowed anymore, the gate is closed.
+}
+...
+gate.close(function() {
+ //... nobody is inside.
+});
+```
+
+## Handle Wrapper
+
+This pattern is for objects that exhibit handle-like facade. Upon instantiation, such objects return handle, which has
+only method ```close```. Such facade is useful for object that are listeners and call for notifications.
+To expose handle facade, one has to implement factory, which has ```initialize``` and ```cleanup``` methods.
+The wrapper takes care to call cleanup only after initialization is completed.
+
+### Definition
+
+```javascript
+var handleWrapper = require('ypatterns').handleWrapper;
+//...
+function factory(...) {
+ function initialize(callback) {
+ //...
+ }
+ function cleanup(callback) {
+ //...
+ }
+ return handleWrapper({ initialize: initialize, cleanup: cleanup });
+}
+```
+
+### Usage
+
+```javascript
+var handle = factory(...);
+...
+handle.close(function() {
+ // Object is closed.
+});
+```
+
+## Sync-Async Facade
+
+This pattern is used to create objects which expose asynchronous instantiation, but can be used synchronously. Better
+behaving usage will use object upon instantiation completion, which ensures asynchronous initialization was completed.
+However, if object is used before completion, this will still work. The facade wrapper invoke synchronous initializer
+if object is used before asynchronous initializer was completed. All this done in a way opaque to usage.
+
+### Usage
+
+```javascript
+var obj = factory(..., function() {
+ // Object initialization completed asynchronously. The object can be used.
+ obj.foo();
+});
+// At this point initialization might not be completed yet, however, the object can be used
+// here as well.
+obj.foo();
+// Function foo will trigger synchronous initializer, which will be invoked before calling foo,
+// if object's initialziation was not completed.
+```
+
+### Definition
+
+```javascript
+var syncasyncFacade = require('ypatterns').syncasyncFacade;
+function factory(..., callback) {
+
+ function createInstance() {
+ // create object
+ // ...
+ return instance;
+ }
+
+ function initializeAsync(instance, callback) {
+ // asynchronous initializer
+ }
+
+ function initializeSync(instance) {
+ // synchronous initializer is invoked only if needed.
+ // initializers should be idempotent, at least, it should be anticipated that synchronous
+ // initializer will be invoked after asynchronous started and asynchronous one should
+ // anticipate synchronous was called in the middle of its execution.
+ }
+
+ return syncasyncFacade({
+ create: createInstance,
+ initializeAsync: initializeAsync,
+ initializeSync: initializeSync
+ },
+ callback);
+}
+```
## License

0 comments on commit e39b045

Please sign in to comment.