===== Javascript binding API - Ecore Poller =====

[[:develop:legacy:api:javascript:ecore|Back to the JS Ecore page]]

**DRAFT**

The Poller module provides infrastructure for creation of pollers.

Pollers are, in essence, callbacks that share a single timer per type. Because not all pollers need to be called at the same frequency the user may specify the frequency in ticks(each expiration of the shared timer is called a tick, in ecore poller parlance) for each added poller. Ecore pollers should only be used when the poller doesn't have specific requirements on the exact times to poll.

This architecture means that the main loop is only woken up once to handle all pollers of that type, this will save power as the CPU has more of a chance to go into a low power state the longer it is asleep for, so this should be used in situations where power usage is a concern.

For now, only 1 core poller type is supported: ''efl.Ecore.Poller.CORE'', the default interval for ''efl.Ecore.Poller.CORE'' is 0.125(or 1/8th) second.

The creation of a poller is extremely simple and only requires one line:

<code javascript>
efl.Ecore.Poller.add(efl.Ecore.Poller.CORE, 1, my_poller_function);
</code>

This sample creates a poller to call my_poller_function at every tick.

==== Constants ====

    * ''efl.Ecore.Poller.CORE'' - The default poller type.

==== Functions ====

=== add(pollerType, interval, callback) ===

Syntax

<code javascript>
function mycallback() { ...};
var poller = efl.Ecore.Poller.add(pollerType, interval, mycallback);
</code>

Parameters

   * pollerType - The type of poller. Must be ''efl.Ecore.Poller.CORE''
   * interval - An integer, between 1 and 32768 inclusive, and must be a power of 2 (i.e. 1,2,4,8,16, ... 16384, 32768). The exact tick in which ''callback'' will be called is undefined, as only the interval between calls can be defined. Ecore will endeavor to keep pollers synchronized and to call as many in 1 wakeup event as possible. If ''interval'' is not a power of two, the closest power of 2 greater than interval will be used.
   * callback - A function taking no arguments to be called when the poller is triggered. It must return either ''efl.Ecore.Mainloop.RENEW'' (or 1) or ''efl.Ecore.Mainloop.Cancel'' (or 0). If it returns the former, it will be called again on the next tick (according to ''interval''). If it returns the latter, it will be deleted automatically, making any references to the poller invalid.

Return value

   * object - An object wrapping this poller instance.
   * null - If it was not possible to add the poller.

=== pollerObject.del() ===

Syntax

<code javascript>
pollerObj.del();
</code>

Deletes the callee poller object from the pollers list.

=== getPollInterval(type) ===

Syntax

<code javascript>
    var interval = efl.Ecore.Poller.getPollInterval(type);
</code>

Parameters

   * type - The desired type of poller. Must be ''efl.Ecore.Poller.CORE''.

Return value

   * number - The current interval (in seconds) between ticks for the given type of poller.

Gets the interval in seconds between successive ticks of the given poller type.

=== setPollInterval(type, interval) ===

Syntax

<code javascript>
efl.Ecore.Poller.setPollInterval(type, poll_time);
</code>

Parameters

   * type - The desired type of poller. Must be ''efl.Ecore.Poller.CORE''.
   * poll_time - The time(in seconds) between ticks of the timer.

Sets the interval (in seconds) between successive ticks for the poller type ''type''.