CreateEventMarshaller
Implementation : Function
Description : Creates an EventMarshaller object.
Signature : CreateEventMarshaller (EventMax[, ClientCallPoint])
Parameters : EventThreshold - Mandatory integer, denoting the size of the
event marshaller's queue. Cannot be
undefined, null, non-numeric or less than 1
in value.
ClientCallPoint - Optional parameter, useful in debugging
client-code, and which is incorporated into
the contents of the message member of the
JavaScript Error-objects that
CreateEventMarshaller can throw. Can have
any value but, ideally, should denote the
point in the application's code where the
the call to CreateEventMarshaller was made.
Returns : An EventMarshaller object
Throws : Error if - EventMax is undefined
- EventMax is null
- EventMax is non-numeric
- EventMax is less than 1
- EventMax argument has a non-integer value
Notes : CreateEventMarshaller can be called as many times as desired.
An EventMarshaller with a queue threshold of 1 will simply
dispatch each event's Response object as the event is posted.
EventMarshaller.PostEvent
Implementation : Function
Description : Causes a Response object that corresponds to the event to be
added to a marshaller's queue.
Signature : PostEvent (ResponseFunc[, FuncArgs[, Priority[, ClientCallPoint]]])
Parameters : ResponseFunc - Mandatory reference to the function that is
to be called when the Response is dispatched.
Cannot be null, must refer to a function.
FuncArgs - Optional value or object-reference that is
passed to the response function upon its
invocation.
Priority - Optional numeric, denoting the priority of
the event. Value, if provided, can be
positive or negative, can have a fractional
component, and can be of any magnitude. Can
have the value of Infinity. Cannot be null,
cannot be non-numeric.
ClientCallPoint - Optional parameter, useful in debugging
client-code, and which is incorporated into
the contents of the message member of the
JavaScript Error-objects that PostEvent can
throw. Can have any value but, ideally,
should denote the point in the application's
code where the call to PostEvent was made.
Returns : Reference to a Response object.
Throws : Error if - ResponseFunc is undefined
- ResponseFunc is null
- ResponseFunc does not refer to a function
- Priority is null
- Priority is non-numeric
- called while the marshaller concerned is dispatching its queue
Notes : If the Priority argument is undefined then a default value of
zero is assigned to the Response object.
If posting an event increments the number of Response objects
in the marshaller's queue to its event maximum, the marshaller
will dispatch the queue.
PostEvent cannot be called on a marshaller that is dispatching
its queue, and doing so will cause the marshaller to halt dispatch
and to throw an exception.
EventMarshaller.UnPostEvent
Implementation : Function
Description : Removes a Response object from a marshaller's queue.
Signature : UnPostEvent (Response[, ClientCallPoint])
Parameters : Response - Mandatory reference denoting the Response object
that is to be removed from the queue.
ClientCallPoint - Optional parameter, useful in debugging
client-code, and which is incorporated into
the contents of the message member of the
JavaScript Error-objects that UnPostEvent can
throw. Can have any value but, ideally,
should denote the point in the application's
code where the call to UnPostEvent was made.
Returns : Either - null, if no Responses remain within the queue.
Or - A reference to the Response object that
corresponds to the event that was posted
after the unposted event was posted
originally, assuming that such an object
exists.
Or - A reference to the Response that was added
prior to the original posting of the
unposted event, assuming there is no
subsequently-posted event.
Throws : Error if - Response argument is undefined
- Response argument is null
- Response argument does not refer to an object
- Response argument does not refer to a Response object
- Response argument does not refer to an object in the marshaller's queue
- called while the marshaller concerned is dispatching its queue
Notes : Once a Response has been removed from a queue, it can only be
re-posted by calling the PostEvent method of an
EventMarshaller object. This means that the application should
drop all references to the object to which the Response
argument refers, thus enabling the interpreter's garbage
collector to recover the storage.
Calling UnPostEvent on a marshaller that is dispatching its
queue will raise an exception.
EventMarshaller.Dispatch
Implementation : Function
Description : Forces an EventMarshaller to dispatch the Responses in its
queue, despite the fact that the total number has not yet
reached the maxium for that marshaller.
Signature : Dispatch ([ClientCallPoint])
Parameters : ClientCallPoint - Optional parameter, useful in debugging
client-code, and which is incorporated into
the contents of the message member of the
JavaScript Error-objects that Dispatch can
throw. Can have any value but, ideally,
should denote the point in the application's
code where the call to Dispatch was made.
Returns : Nothing.
Throws : Error if - Called while the marshaller concerned is dispatching its queue
Notes : Calling Dispatch on a marshaller that is dispatching its queue
will cause the marshaller to halt dispatch and to raise an
exception.
EventMarshaller.GetEventMax
Implementation : Function
Description : Returns the maximum queue-size for an EventMarshaller.
Signature : GetEventMax ()
Parameters : None.
Returns : Integer, denoting the maximum queue-size for the marshaller in
question.
Throws : Nothing.
Notes : GetEventMax always returns a non-negative integral value.
EventMarshaller.SetEventMax
Implementation : Function
Description : Sets the maximum queue-size for an EventMarshaller.
Signature : SetEventMax (NewEventMax[, ClientCallPoint])
Parameters : NewEventMax - Mandatory numeric, denoting the maximum number
of Response objects that the EventMarshaller
can hold before they are dispatched. Must be
greater than 0.
ClientCallPoint - Optional parameter, useful in debugging
client-code, and which is incorporated into
the contents of the message member of the
JavaScript Error-objects that SetEventMax can
throw. Can have any value but, ideally,
should denote the point in the application's
code where the call to SetEventMax was made.
Returns : The old value for the marshaller's event maximum.
Throws : Error if - NewEventMax argument is undefined
- NewEventMax argument is null
- NewEventMax argument is less than 1
- NewEventMax argument has a non integer value
Notes : If the value for NewEventMax is equal to or less than the
current number of Responses in the queue then the marshaller
will dispatch the queue completely, leaving it empty.
Specifying an EventMax of 1 will cause each Response to be
dispatched as soon as it is posted.
Setting an EventMarshaller's event maximum whilst it is
dispatching its queue (e.g. from within a response function that
has been invoked in the process of dispatching that queue) has
no effect on the current queue-dispatch. It does, however, set
the maximum for the next queue to be formed through that
marshaller.
SetEventMax always returns a non-negative integral value.
EventMarshaller.GetEventTotal
Implementation : Function
Description : Returns the total number of events that have been posted to
the marshaller in question.
Signature : GetEventTotal ()
Parameters : None.
Returns : Integer denoting the number of events that have been posted to
a marshaller's queue.
Throws : Nothing.
Notes : GetEventTotal always returns a non-negative integral value.
Response.GetPriority
Implementation : Function
Description : Returns the priority associated with the Response object on which
this is called.
Signature : GetPriority ()
Parameters : None.
Returns : Numeric value denoting the priority of the Response object.
Throws : Nothing.
Notes : Response priorities can have negative or positive values of any
magnitude. Thay can also have the value of Infinity.
Responses with higher priorities are dispatched before those with
lower priorities. Where two or more Responses have the same
priority, they are dispatched in the chronological order in which
they were added to the queue.
Response.SetPriority
Implementation : Function
Description : Sets the priority of the Response object in question.
Signature : SetPriority (NewPriority[, ClientCallPoint])
Parameters : NewPriority - Mandatory numeric, denoting the new priority
of the Response. The value, if provided, can
be positive or negative, can have a
fractional component, and can be of any
magnitude. Can have the value of Infinity.
Cannot be null, and cannot be non-numeric.
ClientCallPoint - Optional parameter, useful in debugging
client-code, and which is incorporated into
the contents of the message member of the
JavaScript Error-objects that SetPriority can
throw. Can have any value but, ideally,
should denote the point in the application's
code where the call to SetPriority was made.
Returns : The value of the Response's old priority.
Throws : Error if - NewPriority is undefined
- NewPriority is null
- NewPriority is non-numeric
Notes : Response priorities can have negative or positive values of any
magnitude.
Responses with higher priorities are dispatched before those
with lower priorities. Where two or more Responses have the
same priority, they are dispatched in the order in which they
were posted.
Setting the priority of a Response once its corresponding
marshaller has begun dispatching its queue does not affect the
subsequent execution order of that queue.
Setting the priority of a Response object after it has been
dispatched from its queue is redundant.
Once dispatched from their respective queues, Response objects are
useless from the point of view of an EventMarshaller. Given
this, and unless client code wishes to put a given Response object
to some other use, all references to the object should be set to
null (or some other appropriate value) to allow the garbage
collector to reclaim the storage.
Response.Func
Implementation : Attribute
Description : Reference to the function that will be invoked for the Response
object concerned when the queue size reaches its threshold, or
when execution is forced by a call to
EventMarshaller.Dispatch.
Type : Function reference.
Notes : This property is not employed directly by an EventMarshaller
object, therefore client code is free to manipulate its value
as it sees fit.
Response.Args
Implementation : Attribute
Description : Reference to the value or object that will be passed to the
response function upon its invocation. May be null or
undefined.
Type : Object reference or value.
Notes : This property is not employed directly by an EventMarshaller
object, therefore client code is free to manipulate its value
as it sees fit.
User_Defined_Obj.Response_Func
Implementation : Function
Description : Performs a user-defined task that corresponds to the posting of
an event to an EventMarshaller. Response functions are called by
an EventMarshaller only once, which is when the marshaller
dispatches its queue.
Signature : User_Defined ([Args[, Priority]])
Parameters : Args - Optional reference to a user-defined object.
Is the value/reference that is passed as the
FuncArgs parameter (if any) that is passed in
a corresponding call to PostEvent. Is
undefined if no value for FuncArgs was
provided.
Priority - Integer denoting the priority of the Event to
which this Response corresponds. Is never
undefined, and has a value of zero, unless
a different value was supplied/set previously
by client code. Can have the formal value of
Infinity.
Returns : Response functions may return anything.
Throws : Response functions may follow any exception throwing/handling
policy they choose.
Notes : If the value for the Priority argument is significant to a
Response function then the function must posit an Args argument
as the first parameter in its signature, even if no
value/reference will be passed as this argument. In this case
the value wll be undefined.
Returning something from a Response function is redundant as any
value/object returned is ignored by the corresponding
EventMarshaller when it dispatches its queue.
Throwing an exception from a Response function upon invocation
by an EventMarshaller, or from within a function that the
Response function invokes directly or indirectly, will halt
dispatch of that marshaller's queue, and will leave any
un-dispatched Responses in the queue. However, throwing an
exception in this way does not corrupt the marshaller in
question, and the object will continue to operate normally.