Convert-Binary-C

 view release on metacpan or  search on metacpan

tests/include/pdclib/Internals.txt  view on Meta::CPAN

---------------------

PDCLib consists of several parts:

1) standard headers;
2) implementation files for standard functions;
3) internal header files keeping complex stuff out of the standard
   headers;
4) the central, platform-specific file _PDCLIB_config.h;
5) platform-specific implementation files;
6) platform-specific, optimized "overlay" implementations (optional).

The standard headers (in ./include/) only contain what they are
defined to contain. Where additional logic or macro magic is
necessary, that is deferred to the internal files. This has been done
so that the headers are actually educational as to what they provide
(as opposed to how the library does it).

There is a separate implementation file (in ./function/{header}/) for
every function defined by the standard, named {function}.c. Not only
does this avoid linking in huge amounts of unused code when you use
but a single function, it also allows the optimization overlay to work
(see below).

(The directory ./functions/_PDCLIB/ contains internal and helper
functions that are not part of the standard.)

Then there are internal header files (in ./include/pdclib/), which
contain all the "black magic" and "code fu" that was kept out of the
standard headers. You should not have to touch them if you want to
adapt PDCLib to a new platform. Note that, if you *do* have to touch
them, I would consider it a serious design flaw, and would be happy

tests/include/pdclib/Internals.txt  view on Meta::CPAN

the constraints of your platform. When you are done, copy the contents
of your platform directory over the source directory structure
of PDCLib (or link them into the appropriate places). That should be
all that is actually required to make PDCLib work for your platform.

Of course, your platform might provide more efficient replacements
for the generic implementations offered by PDCLib. The math functions
are an especially "juicy" target for optimization - while PDCLib does
provide generic implementations for each of them, there are usually
FPU opcodes that do the same job, only orders of magnitude faster. For
this, you might want to create an "optimization overlay" for PDCLib.

Optimization Overlay
--------------------

The basic idea of PDCLib is to provide a generic implementation that
is useable even on platforms I have never heard of - for example, the
OS and/or compiler *you* just wrote and now need a C library for. That
is actually what PDCLib was written for: To provide a C library for
compiler and OS builders that do not want the usual baggage of POSIX
and GNU extensions, licensing considerations etc. etc.

Thus, PDCLib provides generic implementations. They do work, and do
so correctly, but they are not very efficient when compared to hand-
crafted assembler or compiler build-ins. So I wanted to provide a
means to modify PDCLib to run more efficiently on a given platform,
without cluttering the main branch with tons of #ifdef statements and
"featureset #defines" that grow stale quickly.

The solution is the "optimization overlay". Every function has its
own implementation file, which makes it possible to replace them
piecemeal by copying a platform-specific overlay over the main PDCLib
branch to create a PDCLib adapted / optimized for the platform in
question. That overlay could be part of the PDCLib source tree (for
established platforms where maintainers won't bother with PDCLib), or
part of that platform's source tree (for under-development platforms
PDCLib maintainers won't bother with).

So, to use PDCLib on your given platform, you unpack PDCLib (as you
obviously have done already since you are reading this), and copy
the overlay for your platform over the PDCLib source tree structure.

Internal Dependencies
---------------------

Large parts of PDCLib (or any standard library, really) work well in isolation,
and have minimal dependencies. The implementation of <string.h>, for example,
is really just a collection of stand-alone functions.

Other parts, however, depend on each other, and on "background" functionality
that all involved parts need to be aware of and agree upon.

tests/include/pdclib/Notes.txt  view on Meta::CPAN

  can be seen in the atoi() and strtol() function families). This means one or
  two additional function calls, but again reduces memory footprint and eases
  maintenance of the library.

- Function arguments are named exactly as in the standard document.

- The standard is taken quite literally in places. For example, the default
  implementations of memcpy() really copies char-wise. This runs contrary to
  earlier claims of performance, but is consistent with the *letter* of the
  standard, and you will probably use your compiler builtins (through a platform
  overlay) anyhow.

- PDCLib code has no bias towards POSIX; indeed the absence of POSIX tidbits is
  one of its hallmarks. However, PDCLib also has no bias *against* POSIX, and
  when one platform abstraction is as good as another, I chose the POSIX one for
  sheer familiarity. (This is mainly referring to naming and parameter lists of
  OS "glue" functions.)

- Identifiers are tersely named, but not cryptically abbreviated, and should be
  intuitive enough to allow easy understanding of PDCLib inner workings.

tests/include/pdclib/platform/example/Readme.txt  view on Meta::CPAN

"Example" Platform Overlay
==========================

This is an example platform overlay, as described in the main Readme.txt of
this archive. For ease of development, it applies (and tests) correctly on the
machine of the author; no other guarantees can be given.
It should give you a good idea of what is REQUIRED to make a copy of PDCLib
work. There is a lot more you could do, and even some things you SHOULD do, in
order to experience anything but abysmal performance:

- Read / write operations on binary streams, and even on text streams for
  machines that do not do any text conversion, can be made much more efficient
  by using some sort of page buffer instead of the linear buffer implemented
  here. It requires some special and platform-dependent manipulations, though,

tests/include/pdclib/platform/example/functions/stdio/tmpfile.c  view on Meta::CPAN

    if ( randomsource == -1 )
    {
        return NULL;
    }

    for ( ;; )
    {
        /* Get a filename candidate. What constitutes a valid filename and
           where temporary files are usually located is platform-dependent,
           which is one reason why this function is located in the platform
           overlay. The other reason is that a *good* implementation should
           use high-quality randomness instead of a pseudo-random sequence to
           generate the filename candidate, which is *also* platform-dependent.
        */
        unsigned int random;
        read( randomsource, (void *)&random, sizeof( unsigned int ) );
        sprintf( filename, "/tmp/%u.tmp", random );
        /* Check if file of this name exists. Note that fopen() is a very weak
           check, which does not take e.g. access permissions into account
           (file might exist but not readable). Replace with something more
           appropriate.