HJS-MESSAGE
Messaging API of the Hubrisjs javascript framework.
Messaging classes: MessageBroadcaster, MessageHandler, MessageQueue and CountDownTimer.
Installation
Node:
npm install hjs-message --save
Usage
You must before defines a Message containing a description and arbitrary data object that can be sent to a MessageHandler.
This object contains two extra int fields and an extra object field that allow you to not do allocations in many cases.
While the constructor of Message is public, the best way to get one of these is to call Message.obtain() or one of the MessageHanlder.obtainMessage() methods, which will pull them from a pool of recycled objects.
A MessageHandler allows you to send and process Message and Runnable objects associated with a MessageQueue.
Each MessageHandler instance is associated with a single message queue. When you create a new MessageHandler, it is bound to the message queue that is passed has parameter or by an anonymous queue created by the message handler instance if no message queue is specified.
From that point on, it will deliver messages and runnables to that message queue and execute them as they come out of the message queue.
There are two main uses for a MessageHandler:
- to schedule messages and runnables to be executed as some point in the future;
- to enqueue an action to be performed in a Looper.
Scheduling messages is accomplished with the:
- post(Runnable, Object=null)
- postAtFrontOfQueue(Runnable, Object=null)
- postAtTime(Runnable, long=0, Object=null)
- postDelayed(Runnable, long=0, Object=null)
- promise({Function,Function=null,Object=null})
- promiseAtFrontOfQueue({Function,Function=null,Object=null})
- promiseAtTime({Function, Function=null, long=0, Object=null})
- promiseDelayed({Function, Function=null, long=0, Object=null})
- runWithScissors(Runnable, long=0, scheduleTime=200)
- sendEmptyMessage(int)
- sendEmptyMessageAtFrontOfQueue(int)
- sendEmptyMessageAtTime(int, long=0)
- sendEmptyMessageDelayed(int, long=0)
- sendMessage(Message)
- sendMessageAtFrontOfQueue(Message)
- sendMessageAtTime(Message, long=0)
- sendMessageDelayed(Message, long=0)
The promise version allow to work with Promise objects that are standard promise.
The post versions allow you to enqueue Runnable objects to be called by the message queue when they are received.
The sendMessage versions allow you to enqueue a Message object containing a bundle of data that will be processed by the MessageHandler's handleMessage(Message) method (requiring that you implement the method with your own code).
When posting or sending to a MessageHandler, you can either allow the item to be processed as soon as the message queue is ready to do so, or specify a delay before it gets processed or absolute time for it to be processed. The latter two allow you to implement timeouts, ticks, and other timing-based behavior.
Create an empty message
; const EMPTY_MSG = Message;
Create a filled message
; const START_CMD = 0xffddcc;const START_ARG1 = 1;const START_ARG2 = 2; const START_MAP = ;START_MAP; const START_OBJ = data: "started" ; const START_MSG = Message;
Serialize/Deserialize a message to/from json
; const START_MSG = Message; let serialized = START_MSG;console; START_MSG; console;
Create a message handler
; let H = MessageHandler;
Create a message handler with a callback
; //define a callbacklet callback = { //handle your message here //mark the message has handled return true; } ; //somewhere in the codelet H = MessageHandler;
Create a message handler with a custom messenger
; const DELAY_CODE = 0xddeeff;const DEFAULT_CODE = 0xddeeaa; //define a messengerconst M = { let what = msgwhat; let binder = this; if binder if what === DELAY_CODE binder; else binder; } ; //somewhere in the codelet H = MessageHandler; //later in the codeM;M;
Use messenger to send and reply to message across channels
; const HELLO_SEND_CHANNEL = 0x1;const HELLO_RECEIVED_CHANNEL = 0x2; const BYEBYE_CODE = 0x3; let H1 = MessageHandler;// get the default messengerlet M1 = H1;// Subscribe to receive messages across channelsM1; // later somewhere in an another scriptlet H2 = MessageHandler;// get the default messengerlet M2 = H2;// Publish to send messages across channelsM2;
Send an empty message
; const EMPTY_CODE = 0x1; let H = MessageHandler; H;
Send an empty message at front of the queue
; const FIRST_CODE = 0x1;const SECOND_CODE = 0x2;const FRONT_CODE = 0x3; let H = MessageHandler; H;H;
Send an empty message at a specified time in the future
; const HELLO_CODE = 0x11; const START_TIME = Date;const WAIT_TIME = 10000;const UPTIME_MILLIS = START_TIME + WAIT_TIME; let H = MessageHandler; H;
Send an empty message with a delay
; const DELAY_CODE = 0x08;const DELAY_MILLIS = 100; let H = MessageHandler; const START_MILLIS = Date;H;
Send a message
; const WHAT_CODE = 0xddeeff; let H = MessageHandler; let MSG = H; H;
Send a message at the front of the queue
; const FIRST_CODE = 0xffeeff;const EMPTY_CODE = 0xffddff;const PRIORITY_CODE = 0xcceeff; let H = MessageHandler; let MSG_PRIORIY = H; let FIRST_MSG = H; //first messageH;//second messageH;
Send a message at a specified time in the future
; const HELLO_CODE = 0x11;const START_TIME = Date;const WAIT_TIME = 10000;const UPTIME_MILLIS = START_TIME + WAIT_TIME; let H = MessageHandler; let MSG_FUTURE = H; H;
Send a message with a delay
; const DELAY_CODE = 0x21;const DELAY_MILLIS = 100; let H = MessageHandler; let MSG_DELAY = H; const START_MILLIS = Date; H;
Post an anonymous runnable that is executed on the queue
; let H = MessageHandler;H;
Post an runnable instance that is executed on the queue
; let R = { // execute your code here return true; } ; //somewhere in the codelet H = MessageHandler;H;
Post a runnable at front of the queue
; let R = { // execute your code here console; return true; } ; //somewhere in the codelet H = MessageHandler;H;
Post a runnable at a specified time in the future
; const START_TIME = Date;const WAIT_TIME = 10000;const UPTIME_MILLIS = START_TIME + WAIT_TIME; let R = { console; let now = Date; let when = START_TIME; let ellapsed = now - when; let diff = UPTIME_MILLIS - when; console; return true; } ; //we can associate a token object with the runnablelet T = data:"A token that can be anything" ; //later in the codelet H = MessageHandler;H;
Post a runnable with a delay
; const START_TIME = Date;const DELAY_MILLIS = 100; let R = { console; let now = Date; let when = START_MILLIS; let ellapsed = now - when; console; return true; } ; const START_MILLIS = Date; //we can associate a token object with the runnablelet T = data:"A token that can be anything" ; //somewhere in the codelet H = MessageHandler;H;
Post a promise that is executed on the queue
; const loadData = { //load data here...}; let H = MessageHandler; //somewhere in the codeH;
Post a promise that is executed on the queue with the then/catch syntax
; const loadData = { //load data here...}; let H = MessageHandler; //somewhere in the codeH;
Post a promise at front of the queue
; const FIRST_CODE = 0x1;const SECOND_CODE = 0x2;const THIRD_CODE = 0x3; let H = MessageHandler; //later in the codeH;H;
Post a promise at a time in the future
; const START_TIME = Date;const WAIT_TIME = 10000;const UPTIME_MILLIS = START_TIME + WAIT_TIME; let H = MessageHandler; //somewhere in the codeH;
Post a promise with delay
; const START_TIME = Date;const DELAY_MILLIS = 500; let H = MessageHandler; //somewhere in the codeH;
Run with scissors executing a task before a timeout is reached
; let TIMEOUT_CODE = 0xdd; const T = data: "My computed data" ; const R = { ; return true; } ; let H = MessageHandler; H;
Run with scissors wainting until a task is executed
; let COUNT = 0; const R = { console; if COUNT === 5 // notify that the task is completed let msg = Message; task; else COUNT = COUNT + 1; return true; } ; let H = MessageHandler; H;
Test if the queue contains a callback
; const CODE = 0xff; const T = data: "A token"; const R = { console; return true; } ; let H = MessageHandler;H; ;
Test if the queue contains a message
; const CODE = 0xff; const T = data: "A token"; let H = MessageHandler; H; ;
Remove a callback from the queue
; const CODE = 0xff; const R = { // never executed console; return true; } ; const T = {}; let H = MessageHandler;H; ;
Remove a message from the queue
; const CODE = 0xff; const T = data: "A token"; let H = MessageHandler; H; ;
Remove callbacks and messages that have the same token
; const CODE = 0xff; const R = { let hasCallbacks = handler; let handled = hasCallbacks && token; if handled // found token console; // clean references handler; return handled; } ; const T = data: "A token"; let H = MessageHandler; H;
Message broadcaster usage (PUB/SUB pattern)
; //Handler 1 channelsconst SENDER1_CHANNEL = 0x1;const RECEIVER1_CHANNEL = 0x3;//Handler 2 channelsconst SENDER2_CHANNEL = 0x2;const RECEIVER2_CHANNEL = 0x4; let H1 = MessageHandler;// subscribe to the sender channel CODE1 and receive a CODE3H1; let H2 = MessageHandler;// subscribe to the sender channel CODE2 and receive a CODE4H2;// publish to the CODE2 channelH2;
Count down timer usage
; let CDT = millisInFuture: 500 /*time to count down*/ countDownInterval: 100 /*tick interval*/ { console; if millisUntilFinished <= 200 //cancel timer this; } { //timer complete if this console; else console; } ; //start the timerCDTstart;
Contacts
Distributed under the MIT license. See LICENSE
for more information.