[En-Nut-Discussion] Ethernut Docu Improvements

[Harald Kipp]

Hi Matthias,

At 10:10 29.01.2004 +0100, you wrote:

>I tried to read/understand the inter-process communication
>which is obviously done using "events" here.

The docs on this topic are at least insufficient
and based on the old X-Windows saying "Use the
source, Luke!"

On the university I concentrated on documentation,
no big deal if the final product doesn't work. Now
I focus on the product.

Nah, just kidding. Documentation is still most
essential. It's just less fun.

>- the queue is a 16 bit counter and instead of sending
>an event, the task(s) waiting on the "queue" is signaled.

The queue handle is a pointer to a linked list
of thread information structures of all threads
waiting for a specific event.

This priority ordered list of threads queueing up
is called queue.

A single event may be posted to such a queue of
threads, to wake up the thread on top of the queue,
the one with the highest priority among them.

A broadcasted event can be used to wake up all
threads.

>- the "queue" turns out to be a semaphore.

Well...mh...yes...no. In a further abstraction
step a queue can be viewed as a semaphore.
It's the basic IPC (inter process communication) element
in Nut/OS and can be used to implement mutual
exclusion semaphores, counter semaphores or
even message queues.


>- if a task waits on a semaphore ("queue") it is put into
>a queue.

I'd put it that way: If a thread is waiting for an event,
it is put into a queue.

In my view, a semaphore is one additional step. Additional
API calls may be implemented, like
NutMutexCreate
NutMutexAllocate
NutMutexRelease
etc.



>so, I would recommend:
>replace "queue" by semaphore
>replace "event" by signal
>rename event.c to semaphore.c or signal.c
>add a function createSemaphore (HANDLE semaphore) that just sets the
>semaphore value to zero and people know how to start.

Since Nut/OS had been initially build as a most simple
vehicle for implementing a TCP stack, it is limited to
the basic IPC element of events and thread queues.
This limitation isn't a postulated law, though.



>ok, I'm to duck to await YOUR critic.

Critics get bashed in rare cases only. :-)


>a simple question: does anybody need or did implement messsage queues
>or message passing?

I intentionally avoided a message passing OS,
allthough it is very attractive and leads to
very clean implementations.

Somehow it's like comparing C and C++. Considering
clean programming, C++ offers further steps.
But you have to pay for the additional abstraction
with larger and slower code, while C adds just
one layer: Portability. Very generally spoken, of
course.

At
http://www.ethernut.de/en/projects.html
you can find a meesage queue enhancement, contributed
by Ralph Mason. I must admit, that I didn't find the
time to try it (sorry Ralph). But there is a demand
and I'll try to add it after the 3.4 branch has occured.
Allthough, I'd prefer to get Ralph into the CVS developer
status. (Hint! Hint!)

Harald