summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--pages/develop/guides/csharp/core/main-loop.md.txt145
1 files changed, 145 insertions, 0 deletions
diff --git a/pages/develop/guides/csharp/core/main-loop.md.txt b/pages/develop/guides/csharp/core/main-loop.md.txt
new file mode 100644
index 000000000..8d91e1b4d
--- /dev/null
+++ b/pages/develop/guides/csharp/core/main-loop.md.txt
@@ -0,0 +1,145 @@
1---
2~~Title: Main Loop Programming Guide in C#~~
3~~NOCACHE~~
4---
5
6# Main Loop Programming Guide in C# #
7
8The EFL is event-driven. This means that execution usually takes place within an internal EFL *Main Loop*. The application is notified through function callbacks of virtually any event happening on the computer. This is typically more efficient than *polling* for events, whereby the application has to repeatedly ask if a certain event has occurred. When nothing is happening (no events are pending) the main loop enters the *idle state* during which the CPU consumes very little power.
9
10EFL manages timers and user interface events amongst many other things and even provides a simple mechanism for applications to perform conventional data polling if required.
11
12## Prerequisites ##
13
14* Read the [Hello World in C#](/develop/tutorials/csharp/hello-world.md) tutorial to learn how to instantiate EFL objects.
15* Read the [Events Programming Guide](events.md) to learn how to register callbacks, which can be triggered by events.
16
17## The Application Main Loop ##
18
19For convenience, when your application starts, EFL creates one Main Loop for you, called the *Application Main Loop*. You can use it as the parent for any object you create that requires a main loop (Like [Promises and Futures](/develop/guides/c/eina/futures.md), for example).
20
21In the [Hello World](/develop/tutorials/csharp/hello-world.md) tutorial you learned that you can retrieve the Application Main Loop like this:
22
23```csharp
24var mainloop = efl.App.GetLoopMain();
25```
26
27This guide will put the application's main loop to a variety of uses.
28
29## Timers ##
30
31Timers allow events to be triggered periodically after the given time has elapsed. After an event callback has been registered with the timer, it will be called at regular intervals.
32
33You can find usage examples in the [EFL examples repository](https://git.enlightenment.org/tools/examples.git): [`reference/csharp/core/src/core_idler.cs`](https://git.enlightenment.org/tools/examples.git/tree/reference/csharp/core/src/core_idler.cs) and [`reference/csharp/core/src/core_poll.cs`](https://git.enlightenment.org/tools/examples.git/tree/reference/csharp/core/src/core_poll.cs).
34
35### Creating and Destroying Timers ###
36
37Timers are EFL objects. You can create them with the `new` operator as all other EFL objects, with an optional parent and initialization method (as seen in the [Hello World in C#](/develop/tutorials/csharp/hello-world.md) tutorial):
38
39```c
40var timer_object = new efl.Loop_Timer(mainloop, (efl.ILoop_Timer etimer) => {
41 // Timer configuration
42});
43```
44
45Timers do not need to have a parent. However it is convenient to create them under the application Main Loop, so the parent can manage destroying the timer.
46
47### The Timer Callback ###
48
49Register the callback using the `+=` operator as explained in the [Events Programming Guide](events.md), and the `TickEvt` event.
50
51```csharp
52timer_object.TickEvt += (object sender, EventArgs e) => {
53 Console.WriteLine("TIMER: timer callback called");
54};
55```
56
57The callback has the usual event handler signature:
58
59```csharp
60void callback(object sender, EventArgs e);
61```
62
63This callback will be continuously triggered in the configured time intervals.
64
65### Configuring a Timer ###
66
67The `Interval` property controls the amount of time between callback triggers in **seconds**:
68
69```csharp
70timer_object.SetInterval(0.01); // In seconds
71timer_object.GetInterval();
72```
73
74The **time left** before the next trigger of the timer can be retrieved through the `Pending` read-only property:
75
76```csharp
77timer_object.GetPending();
78```
79
80The current interval can be `Reset` with:
81
82```csharp
83timer_object.Reset();
84```
85
86The current interval can also be extended using `Delay()`, effectively delaying all future triggers of the timer by a given number of **seconds**:
87
88```csharp
89timer_object.Delay(1); // In seconds
90```
91
92### Pausing a Timer ###
93
94Timers are paused by preventing them from emitting any events, as explained in the [Events Programming Guide](events.md).
95
96Pause a timer with:
97
98```csharp
99timer_object.FreezeEvent();
100```
101
102Resume from the previous time index:
103
104```csharp
105timer_object.ThawEvent();
106```
107
108## Idlers ##
109
110When there are no events to process the EFL main loop enters the Idle state, consuming very little CPU power. You can receive a notification when the Idle state starts or stops.
111
112EFL defines three different events you can use to be notified of the above conditions:
113
114* `IdleEnterEvt`: Main loop enters the idle state.
115
116* `IdleExitEvt`: Main loop exits the idle state.
117
118* `IdleEvt`: Main loop is in the idle state, meaning that it has nothing else to do.
119
120 > **NOTE:**
121 > This callback will be invoked frequently consuming a significant amount of CPU resources. This also defeats the point of an event-driven application: heavy calculations should be performed on a separate thread or they will block the main loop. This can lead to an unresponsive user interface and other issues.
122
123Register a callback to be notified of these events using the `+=` operator, as described in the [Events Programming Guide](events.md).
124
125You can also view the example in the EFL examples repository: [`reference/csharp/core/src/core_idler.cs`](https://git.enlightenment.org/tools/examples.git/tree/reference/csharp/core/src/core_idler.cs).
126
127## Polling ##
128
129In the rare case where EFL does not provide the event you want, you can resort to conventional application-driven polling. EFL can still manage the scheduling of the periodic polling, calling you back when it is time to perform the poll.
130
131You can choose from among the predefined polling priorities depending on which event you use to register your callback on the application's Main Loop object:
132
133* `PollHighEvt`: For events that may happen multiple times per second.
134
135* `PollMediumEvt`: For events that may happen multiple times per minute.
136
137* `PollLowEvt`: For events that may happen multiple times every 15 minutes.
138
139The actual polling period is controlled by EFL and can be changed system-wide.
140
141You can find usage examples in the EFL examples repository: [`reference/csharp/core/src/core_poll.cs`](https://git.enlightenment.org/tools/examples.git/tree/reference/csharp/core/src/core_poll.cs)
142
143## Further Reading ##
144[`Efl.Loop` API Reference](/develop/api/efl/loop)
145: Detailed documentation for the Loop object (in C)