<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class VMSlot - Class VMSlot</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./funset.html"><span>Function sets</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Class VMSlot</h1>
<p class="faldoc_brief">VM Interface for message oriented programming operations. </p>
<p class="faldoc_funcdecl">
<b>class</b> VMSlot( [name] )
</p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#assert">assert()</a></td><td>Creates a message assertion on this certain message slot. </td></tr>
<tr><td><a href="#broadcast">broadcast()</a></td><td>Performs broadcast on this slot. </td></tr>
<tr><td><a href="#first">first()</a></td><td>Gets an iterator to the first subscriber. </td></tr>
<tr><td><a href="#getAssert">getAssert()</a></td><td>Gets the item asserted for this slot. </td></tr>
<tr><td><a href="#getEvent">getEvent()</a></td><td>Returns an event (as a child VMSlot) handled by this slot. </td></tr>
<tr><td><a href="#last">last()</a></td><td>Gets an iterator to the last subscriber. </td></tr>
<tr><td><a href="#name">name()</a></td><td>Returns the name of this slot </td></tr>
<tr><td><a href="#prepend">prepend()</a></td><td>Registers a callback handler that will be called before the others. </td></tr>
<tr><td><a href="#register">register()</a></td><td>Registers a listener for a specific event. </td></tr>
<tr><td><a href="#retract">retract()</a></td><td>Removes a previous assertion on a message. </td></tr>
<tr><td><a href="#send">send()</a></td><td>Performs an event generation on this slot. </td></tr>
<tr><td><a href="#subscribe">subscribe()</a></td><td>Registers a callback handler on this slot. </td></tr>
<tr><td><a href="#unsubscribe">unsubscribe()</a></td><td>Unregisters a callback handler from this slot. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<p class="faldoc_funcdecl">
<b>class</b> VMSlot( [name] )
</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">name</td><td class="faldoc_optparamdesc">The name of the mesasge managed by this VMSlot. </td></tr>
</table>
<br/>
<p class="item_brief">VM Interface for message oriented programming operations. </p>
<p class="faldoc_text"> The VMSlot instance is a direct interface to the messaging facility of the VM creating it. It is implicitly created by the <a href="./functions.html#getSlot">getSlot</a> function, but it can be directly created by the user. </p>
<p class="faldoc_text">If a slot with the given name didn't previously exist, a new message slot is created in the virtual machine, otherwise the already existing slot is wrapped in the returned instance. </p>
<pre class="faldoc_code">
// create a message slot
x = VMSlot( "message" )
x.subscribe( handler )
...
y = VMSlot( "message" )
y.broadcast( "value" ) // handler is called.
</pre>
<p class="faldoc_text"> Same happens if the VMSlot is created via <a href="./functions.html#getSlot">getSlot</a>, or implicitly referenced via <a href="./functions.html#subscribe">subscribe</a> function. Slots are considered unique by name, so that comparisons on slots are performed on their names. </p>
<p class="faldoc_text"> If the <b>name</b> parameter is not given, the slot will be created as "anonymous", and won't be registered with this virtual machine. It will be possible to use it only through its methods. </p>
<a name="ev_anonym_slots"><h2 class="faldoc_section">Anonymous slots </h2></a>
<p class="faldoc_text"> An anonymous slot can be created using an empty call to the VMSlot class constructor. This will make the slot private for the users that can access it; in other words, the slot won't be published to the VM and it won't be possible to broadcast on it using the standard functions <a href="./functions.html#broadcast">broadcast</a> or <a href="./functions.html#assert">assert</a> functions. </p>
<a name="ev_slots"><h2 class="faldoc_section">Automatic broadcast marshaling </h2></a>
<p class="faldoc_text">If a listener subscribed to a slot is a callable item, then it's called in case of broadcasts. If it's a non-callable property provider (class instances, blessed dictionaries, non-callable arrays) then a callable property named like "on_<slot_name>" is searched; if found, it's called (as a method of the host entity), otherwise a catch all method named "__on_event" is searched. </p>
<p class="faldoc_text">If the "__on_event" method is found, it's called with the first parameter containing the broadcast name. Otherwise, an access error is raised. </p>
<a name="ev_events"><h2 class="faldoc_section">Events </h2></a>
<p class="faldoc_text"> Events are "named broadcasts". They are issued on slots and excite all the listeners that are subscribed to that slot. The main difference is that automatic marshalling is directed to the name of the <i>event</i> rather to the name of the <i>slot</i>. </p>
<p class="faldoc_text">See the following code: </p>
<pre class="faldoc_code">
object Receiver
_count = 0
function display(): > "Count is now ", self._count
function on_add(): self._count++
function on_sub(): self._count--
function __on_event( evname ): > "Received an unknown event: ", evname
end
s = VMSlot() // creates an anonymous slot
s.subscribe( Receiver )
s.send( "add" ) // Instead of sending a broadcast ...
s.send( "add" ) // ... generate some events via send()
s.send( "A strange event", "some param" ) // will complain
Receiver.display() // show the count
</pre>
<p class="faldoc_text"> The <b><i>VSMlot.send</i></b> method works similarly to the <a href="./class_VMSlot.html#broadcast">VMSlot.broadcast</a> method, but it allows to specify an arbitrary event name. Callbacks subscribed to this slot would be called for <i>every</i> event, be it generated through a broadcast or via a send call. </p>
<a name="ev_subslots"><h2 class="faldoc_section">Registering to events and Sub-slots </h2></a>
<p class="faldoc_text"> While callbacks subscribed to the slot will be excited no matter what kind of event is generated, it is possible to <i>register</i> callbacks to respond only to <i>particular</i><i>events</i> via the <a href="./class_VMSlot.html#register">VMSlot.register</a> method. </p>
<p class="faldoc_text">See the following example: </p>
<pre class="faldoc_code">
slot = VMSlot() // creates an anonymous slot
slot.register( "first",
{ param => printl( "First called with ", param ) } )
slot.register( "second",
{ param => printl( "Second called with ", param ) } )
// send "first" and "second" events
slot.send( "first", "A parameter" )
slot.send( "second", "Another parameter" )
// this will actually do nothing
slot.broadcast( "A third parameter" )
</pre>
<p class="faldoc_text"> As no callback is <i>subscribed</i> to the slot, but some are just <i>register</i> to some events, a generic <i>broadcast</i> will have no effect. </p>
<p class="faldoc_text"> An interesting thing about registering to events is that a slot keeps tracks of callbacks and items registered to a specific event via a named slot. For example, to know who is currently subscribed to the "first" event, it's possible to call the <a href="./class_VMSlot.html#getEvent">VMSlot.getEvent</a> method and inspect the returned slot. Any change in that returned slot will cause the event registration to change. </p>
<p class="faldoc_text">For example, continuing the above code... </p>
<pre class="faldoc_code">
//...
fevt = slot.getEvent( "first" )
// display each subscribed item
for elem in fevt: > elem.toString()
// and broadcast on the event first
fevt.broadcast( "The parameter" )
</pre>
<p class="faldoc_text">As seen, a broadcast on a sub-slot is equivalent to an event send on the parent slot. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> It is then possible to cache repeatedly broadcast slots, so that the virtual machine is not forced to search across the subscribed events. </p>
<p class="faldoc_text"> This structure can be freely replicated at any level. In the above example, <b>fevt</b> may be subject of send() and register() method application, and its own events can be retrieved trough its <a href="./class_VMSlot.html#getEvent">VMSlot.getEvent</a> method. </p>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="assert">assert()</a></h3>
<p class="item_brief">Creates a message assertion on this certain message slot. </p>
<p class="faldoc_funcdecl">VMSlot.assert( data )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">data</td><td class="faldoc_paramdesc">The value of the assertion. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If there are already subscribed callbacks for this message a broadcast on them is performed now. </p>
</p>
<h3 class="faldoc_funcname"><a name="broadcast">broadcast()</a></h3>
<p class="item_brief">Performs broadcast on this slot. </p>
<p class="faldoc_funcdecl">VMSlot.broadcast( ... )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">Extra parameters to be sent to listeners. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="first">first()</a></h3>
<p class="item_brief">Gets an iterator to the first subscriber. </p>
<p class="faldoc_funcdecl">VMSlot.first( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An iterator to the first subscriber of this message slot. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="getAssert">getAssert()</a></h3>
<p class="item_brief">Gets the item asserted for this slot. </p>
<p class="faldoc_funcdecl">VMSlot.getAssert( [default] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">default</td><td class="faldoc_optparamdesc">If given, instead of raising in case the essartion is not found, return this item. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_MessageError.html">MessageError</a></td><td class="faldoc_raisedesc">if the item has not an assertion and a default is not given. </td></tr>
</table>
</td></tr>
</table>
<h3 class="faldoc_funcname"><a name="getEvent">getEvent()</a></h3>
<p class="item_brief">Returns an event (as a child VMSlot) handled by this slot. </p>
<p class="faldoc_funcdecl">VMSlot.getEvent( event, [force] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">event</td><td class="faldoc_paramdesc">A string representing the event name. </td></tr>
<tr><td class="faldoc_optparam">force</td><td class="faldoc_optparamdesc">Pass true to create the event if it is not existing. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> a VMSlot representing the given event in this slot, or <b>nil</b> if not found. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This method returns a named VMSlot that will be excited by <a href="./class_VMSlot.html#send">VMSlot.send</a> applied on this slot with the same <b>event</b> name. </p>
<p class="faldoc_text"> In other words, subscribing or unsubscribing items from the returned slot would add or remove listeners for a <a href="./class_VMSlot.html#send">VMSlot.send</a> call on this slot. </p>
<p class="faldoc_text"> Also, a broadcast on the returned VMSlot has the same effect of a <a href="./class_VMSlot.html#send">VMSlot.send</a> with the same name as the <b>event</b> passed. </p>
</p>
<h3 class="faldoc_funcname"><a name="last">last()</a></h3>
<p class="item_brief">Gets an iterator to the last subscriber. </p>
<p class="faldoc_funcdecl">VMSlot.last( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An iterator to the last subscriber of this message slot. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="name">name()</a></h3>
<p class="item_brief">Returns the name of this slot </p>
<p class="faldoc_funcdecl">VMSlot.name( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The name of the event bind to this slot (as a string). </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="prepend">prepend()</a></h3>
<p class="item_brief">Registers a callback handler that will be called before the others. </p>
<p class="faldoc_funcdecl">VMSlot.prepend( handler )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">handler</td><td class="faldoc_paramdesc">The callable that must be unregistered. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="register">register()</a></h3>
<p class="item_brief">Registers a listener for a specific event. </p>
<p class="faldoc_funcdecl">VMSlot.register( event, handler )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">event</td><td class="faldoc_paramdesc">A string representing the event name. </td></tr><tr><td class="faldoc_param">handler</td><td class="faldoc_paramdesc">Handler to associate to this event. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function associates the given <b>handler</b> to a sub-slot named after the <b>event</b> parameter. This operation is equivalent to call <a href="./class_VMSlot.html#getEvent">VMSlot.getEvent</a>() to create the desired sub-slot, and then call <a href="./class_VMSlot.html#subscribe">VMSlot.subscribe</a>() on that named slot. </p>
</p>
<h3 class="faldoc_funcname"><a name="retract">retract()</a></h3>
<p class="item_brief">Removes a previous assertion on a message. </p>
<p class="faldoc_funcdecl">VMSlot.retract( )</p>
<h3 class="faldoc_funcname"><a name="send">send()</a></h3>
<p class="item_brief">Performs an event generation on this slot. </p>
<p class="faldoc_funcdecl">VMSlot.send( event, ... )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">event</td><td class="faldoc_paramdesc">Event name. </td></tr><tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">Extra parameters to be sent to listeners. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The send method works as broadcast, with two major differences; </p>
<ul>
<li>In case of objects being subscribed to this slot, the name of the broadcast message is that specified as a parameter, and not that of this slot. This means that automatic marshaling will be performed on methods named like on_<event>, and not on_<self.name>. </li><li> Items registered with <a href="./class_VMSlot.html#register">VMSlot.register</a> gets activated only if the <b>event</b> name is the same to which they are registered to. </li>
</ul>
</p>
<h3 class="faldoc_funcname"><a name="subscribe">subscribe()</a></h3>
<p class="item_brief">Registers a callback handler on this slot. </p>
<p class="faldoc_funcdecl">VMSlot.subscribe( handler, [prio] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">handler</td><td class="faldoc_paramdesc">A callable item or instance providing callback support. </td></tr>
<tr><td class="faldoc_optparam">prio</td><td class="faldoc_optparamdesc">Set to true to have this handler called before the previous ones. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="unsubscribe">unsubscribe()</a></h3>
<p class="item_brief">Unregisters a callback handler from this slot. </p>
<p class="faldoc_funcdecl">VMSlot.unsubscribe( handler )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">handler</td><td class="faldoc_paramdesc">The callable that must be unregistered. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_CodeError.html">CodeError</a></td><td class="faldoc_raisedesc"> if the <b>handler</b> is not registered with this slot. </td></tr>
</table>
</td></tr>
</table>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./funset.html">Function sets</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./globals.html">Globals</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
