Re: [ECOS] C++ API Reference manual

[NavEcos <ecos at navosha dot com>]

On Sunday 11 August 2002 04:38, Nick Garnett wrote:
> NavEcos <ecos@navosha.com> writes:
> > If anybody is interested my company has produced a little reference
> > manual that may be of use to other people.  It documents the C++
> > kernel interface.
> >
> > The document is "alpha" meaning it may have plenty of errors and/or
> > mistakes or it may not.  If you spot any errors and point them out
> > to me I will update and correct the document.  The accuracy of the API
> > is directly related to how often I used that feature of the API.  Some of
> > the features I've never used.
> >
> > You may find it here:
> >
> > http://navosha.dynu.com
> >
> > I created this document as an excercise to get to know some of the
> > lesser known features of eCos.  I also have noticed that the C++
> > interface is more feature rich than the C interface.
> >
> > I've put it more or less under the open publication license
> > (http://www.opencontent.org/openpub/) the same license that many  of
> > the eCos documents are already under.
>
> Good work, but be careful. There is no guarantee that the C++
> interface will remain constant. It was designed as an internal
> interface for use by the components of eCos -- which is why it has
> never been documented, we don't want users to rely on it.  We have
> made significant changes to it in the past and may do so again in the
> future.

The reason I started reading it is because I noticed that there
is additional functionality in the C++ interface not available in
the C interface, for example getting a thread's name or walking
through all the threads to check for stack usage, and other
nifty things.

The binary semaphore is probably one of the most useful constructs
that is available in C++ but not in C.  I emulated one with a counting
semaphore but the implementation was a bit sloppy.

> Only the C API, POSIX and uITRON are guaranteed to remain backward
> compatible. I always strongly advise people against using the C++
> interface from applications.

I am considering adding a message queue, i.e. a variable sized
message box.  Currently I have it implemented with two counting
semaphores.  If I were to modify it to use signals would you be
willing to incorporate it into the main tree?  I think many people
would find this useful, not just me.

> I would suggest adding a warning to this effect at the start of the
> document.

Good point.  I will do this soon.

Also, please, if you find errors, and I'm sure you will, don't
hesitate to let me know so I can make the documentation
accurate.

-Rich

-- 
Before posting, please read the FAQ: http://sources.redhat.com/fom/ecos
and search the list archive: http://sources.redhat.com/ml/ecos-discuss