事件同步

Events are very valuable and an often used tool for the synchronization in multi-threaded applications. In the »RealTime Suite« special events are required, because they have to be set from the kernel level, too. This is not supported by normal Windows-events. Additionally special events can be created to synchronize real-time-tasks.

事件是应用于多线程应用程序的线程之间同步的经常使用的工具。在Kithara RTS实时套件的事件比较特殊，因为他们必须从内核层设置。Windows的事件可以不是必须从内核中设置。另外可以创建特殊事件实现对多个实时任务的同步。

Creating events

创建事件

Note: During creation of an event a flag decides if the event is a thread- or a task-event! As its name suggests, a thread-event can only block a thread and a task-event can only block a task!

备注：在创建事件时的标志决定事件是一个线程事件还是一个任务事件！正如其名称所暗示的，线程事件只能阻塞线程，任务事件只能阻塞任务！

KS_createEvent creates an event and returns an event handle (This is not a Windows-Event-Handle and must not be used with/within Windows-function) which is required for all other event functions.

使用KS_createEvent函数可以创建一个事件并返回一个事件句柄，这个事件句柄可以被其他关于事件操作的函数使用（这不是Windows事件句柄，禁止在Windows函数中使用）。

The event can be named with a system wide unique name. In this way it is possible to use one event in different application instances. The name is given to the parameter name, and has to be zero-terminated, maximum string length is 64. Use the flags parameter to choose between normal thread-events, task-events (KSF_KERNEL_EXEC) and the manual-reset-option (KSF_MANUAL_RESET).

在系统范围内，事件的名称是唯一的。因此多个不同的应用程序可以共用一个事件。这个名字又参数name指定，并必须为以零结尾的，并且字符串最大长度为64。参数flag可以确定事件的类型，这些类型包括普通线程事件和任务事件(KSF_KERNEL_EXEC) 和手动复位选项之间选取 (KSF_MANUAL_RESET)。

Event state changes

事件的状态改变

The state of an event is changeable with different functions. Those functions work differently on an auto-reset-event respectively on a manual-reset-event.

使用不同的函数可以改变事件的状态。这些函数对自动复位事件和手动复位事件的处理方式不同。

Set event

设置事件

The function KS_setEvent will set the event given in hEvent. An auto-reset-event will be consumed and reset automatically from the highest thread or task waiting for it. A manual-reset-event will stay set until the reset-function is called for this event.

使用 KS_setEvent 函数可以设置在参数hEvent指定的事件。在高优先级的线程或任务等待的自动复位事件会被消耗掉或自动复位【看原文，需要结合场景】，手动复位的事件将保持设置，直到复位函数调用此事件。

Reset event

重置事件

KS_resetEvent will reset a manual-reset-event if it is currently set.

KS_resetEvent函数可以重置手动复位的事件。

Pulse event

暂停事件

The function KS_pulseEvent sets and immediately resets the event. This function can be called in three different situations (the event is currently not set):

• No task/thread is waiting: nothing happens
• One or more tasks/threads are waiting for an auto-reset-event: the one with highest priority will consume the event and the event is reset.
• One or more tasks/threads are waiting for a manual-reset-event: all will consume the event and the event is reset afterwards.

The event is reset after the call.

KS_pulseEvent函数置位或立即复位事件。这个函数可以在三种不同的情况下调用（前提是这个事件目前还没有被设置）：

• 没有任务/线程正在等待：没有事情发生
• 一个或多个任务/线程正在等待自动复位事件：其中具有最高优先级的将会消耗这个事件和剩下的事件。
• 一个或多个任务/线程正在等待手动复位事件：将所有事件消耗，而后将改事件复位。

这个事件在函数调用后复位。

Blocking threads or tasks

阻塞线程或任务

This is the main function of an event. The event can be used to block a thread or task. Events created with KSF_KERNEL_EXEC can block task only, events without that flag can block threads only.

这是一个关于事件的主要函数。事件可以被用于阻塞线程或任务。使用参数FLAG为KSF_KERNEL_EXEC创建的事件只能阻塞任务，未设置FLAG而创建的事件只能阻塞线程。

Waiting for an event

等待一个事件

If the function KS_waitForEvent is called, the current thread or task will be blocked. It is possible to determine a timeout-value via the parameter timeout. The timeout-value represents 100 ns-units (like all time-values). The thread or task will be blocked until the event is set and can be consumed by the current thread or task. Of course only if the timeout is not reached. To use an infinite timeout, set the parameter to zero.

如果函数KS_waitForEvent被调用，当前线程或任务将被阻止。这有可能通过参数超时来确定超时值。超时值指100纳秒（ns）的单位（就像所有时间值）。线程或任务将被阻塞直到事件被设置，并且可以由当前线程或任务被消耗掉。当然，只有超时时间没达到时。要使用无限超时，需要将参数设置为零。

Query event state

查询事件状态 

To read out the current state of an event, the KS_getEventState function can be called.

KS_getEventState函数用来读取当前事件的状态。

Remove events

移除事件

To remove an event the function KS_closeEvent is used. If the event was used in multiple application instances, it has to be closed in every instance before it is actually removed.

KS_closeEvent可以用于移除一个事件。如果事件是在多个应用程序实例中使用，那么每一个应用程序实例被关闭之前必须移除事件。