How Iguana Processes your Main Module

Introduction

In the Iguana Translator variables are initialized at different times depending on where they are declared.

In the main module variables declared outside the main() function are initialized once when the channel is started. Variables declared within the main() function are initialized every time a message is processed by the Translator.

Note: The same principle applies to other modules that are “required” in the code. Variables declared within a module but outside a function (i.e., variables with module scope) are initialized once when the channel starts, and variables within functions are initialized whenever that function is called.

Tip: It is a recommended Best Practice Name “constant” values using ALLCAPS to indicate that they are CONST type values and should not be changed. However please be aware that this just a convention as there is no static CONST type in Lua (unlike compiled languages like C, C++ etc.). Using ALLCAPS lets programmers know that these variables are constants and should not be changed (if they are named like other variables there is no easy way to tell).

You should be aware that because this is “just” a convention it means badly behaved code can (accidentally) update these (pseudo) CONST values.

Task [top]

Explain how (which part of) the code in the main module runs:

  1. When a channel starts up.
  2. When a channel processes a message.

Implementation [top]

Suppose you have the simple code below:

main module initialization

mymodule initialization

When you START this channel, here are the code execution steps:

Step Module Function Line Actions
1 main.lua
 none line 1 set MAINCONST = 2
2 main.lua none line 2 jump into mymodule.lua
3 mymodule.lua none line 1 set MODCONST = 1 → return to main.lua
4 main.lua main() line 4-5 call mod.myfunction() → jump to mymodule.lua
5 mymodule.lua mymodule.myfunction() line 5-7 return MODCONST → return to main.lua
6 main.lua main() line 6-7 trace MAINCONST → end

And these are the same steps in pictures:

  1. main.lua: set MAINCONST = 2
    main process 1
  2. main.lua: jump into mymodule.lua
    main process 2
  3. module.lua: set MODCONST = 1 → return to main.lua
    main mod process 1
  4. main.lua: call mod.myfunction() → jump to mymodule.lua
    main process 3
  5. module.lua: return MODCONST → return to main.lua
    main mod process 2
  6. main.lua: trace MAINCONST → end
    main process 4

When a MESSAGE triggers this channel, here are the code execution steps:

Step Module Function Line Actions
1 main.lua main() line 4-5 call mod.myfunction() → jump to mymodule.lua
2 mymodule.lua mymodule.myfunction() line 5-7 return MODCONST → return to main.lua
3 main.lua main() line 6-7 trace MAINCONST → end

And these are the same steps in pictures:

  1. main.lua: call mod.myfunction() → jump to mymodule.lua
    main process 3
  2. module.lua: return MODCONST → return to main.lua
    main mod process 2
  3. main.lua: trace MAINCONST → end
    main process 4

How it works [top]

When you start a channel the Translator runs all the code in the main module — this only occurs once when the channel starts. When a running channel receives a message, from its queue, only the main() function is called. This means that initialization of “constant” variables (and functions) outside of the main() function only occurs once when the channel starts.

When you START a channel: The Iguana Translator runs the complete main module once.

This is the result:

  1. The Translator will initialize any instance variables that are outside your main() function:
    • The values CONSTANT variables are initialized to will persist until the channel is stopped and restarted again.
      Note: You could change set the values for CONSTANT variables in other code but this is not best practice (in fact it is a very bad idea).
  2. The Translator will make any function calls that are outside your main() function:
    • Functions calls outside main() can be useful for more complex initialization (one-off) tasks.
    • Our code example kept it simple and did not make any function calls outside main().
  3. Any “required” modules are also initialized:
    • Variables declared within a module but outside a function (i.e., variables with module scope) are initialized once when the channel starts.
    • Function calls within a module but outside a function (i.e., calls with module scope) are run once when the channel starts.
    • Functions within modules are not run by a “require” command (unlike the main() function which is a special case on startup)
  4. The Translator also runs the main() function.

When a MESSAGE triggers a running channel: Iguana uses the main() function as the entry point, and only runs the code within the main() function.

This is the result:

  1. The Translator only runs the main() function.

More information [top]

Tagged: