Dynamic timers support

[djphoenix]

Fixes #1416.

• This PR is compliant with the contributing guidelines (if not, please describe why).
• I have thoroughly tested my contribution.
• The code changes are reflected in the documentation at docs/en/*.

I'll write docs soon, now will be great if anyone test this stuff.

[devsaurus]

Great, I'll have a look.

[devsaurus]

The code can emit a clearer error message if you query the element type first and then have luaL_argcheck() report a wrong type with something like "timer object or numerical ID expected".

[devsaurus]

The following code PANICs when the timer expires:

tim = tmr.create()
tim:register(5000, tmr.ALARM_SINGLE, function(t)
    print("timer expired")
    print(t:state())
    t:unregister()
end)

tim:start()
print(tim:state())

-- PANIC when object is destroyed before timer expired
tim = nil

Edit: No, it doesn't. My bad.

[devsaurus]

Please stick to a consistent indentation style.
If unsure, follow the Lua style: 2 space indent + 1TBS + no trailing spaces.

[djphoenix]

ACK

[djphoenix]

Thanks @devsaurus for review. I will fix codestyle & logics and push it back today.

[devsaurus]

Very much appreciated @djphoenix. It's been just some minor aesthetic things while functionality is great.

[djphoenix]

Fixed all of your comments and began to write docs.

[djphoenix]

All done. Also fixed self-unref if mode was SINGLE or SEMI and timer was not rearmed during callbeck.

Now this works OK without leaks:

function setTimeout(t, f)
    return tmr.create():alarm(t, tmr.ALARM_SINGLE, f)
end

setTimeout(1000, function()
    print("TICK!")
end)

[marcelstoer]

I'm missing the deprecation notes for the old-style functions in code and docs.

[djphoenix]

My propose is now only add new functions. We may think about deprecation process in another thread.

[marcelstoer]

You need to think about deprecating the old/existing stuff whenever you add something new that serves as a replacement. Deprecating doesn't mean removing but adding a note to others indicating that existing functionality will or might be removed in the future. That way we give developers some slack to transition to using the new API. Also, we remove reluctance as an obstacle to actually removing old API.

[djphoenix]

Ohm. OK. Can you point me to example/instruction of deprecation notes? So I'll do it some later cause AFK.

[marcelstoer]

We have no guidelines for that, sorry. In essence the word "deprecated" in code and docs is all it takes e.g. http://nodemcu.readthedocs.io/en/latest/en/modules/node/#nodekey-deprecated.

[djphoenix]

@marcelstoer check it... And we really need guidelines to deprecation process, both for arguments or functions or whole modules.

[devsaurus]

👍 from my side.

[eku]

@djphoenix how long will it take till http://nodemcu.readthedocs.io/en/master/en/modules/tmr/ is updated?

[djphoenix]

@eku you watching to master-branch docs, they're updating parallel with code at "master drops". Now this feature is only in dev branch, so look for dev docs ;)

[marcelstoer]

@eku There's a fly-out menu in the lower left corner with which you, amongst others, can select the branch.