Refactor Liblumiera Out
=======================

// please don't remove the //word: comments

[grid="all"]
`------------`-----------------------
*State*         _Idea_
*Date*          _Fr 22 Apr 2011 10:46:50 CEST_
*Proposed by*   Christian Thaeter <ct@pipapo.org>
-------------------------------------

[abstract]
********************************************************************************
liblumiera contains alot useful and reuseable code which is already in use by
other projects
********************************************************************************

Description
-----------
//description: add a detailed description:
Over the time we've put some efforts into the liblumiera. I've added
some from my code which predates the lumiera project which I am using
on many other projects. This now caused that I maintain this sources in
different unrelated projects and have to cross merge and update stuff
when I do updates and fixes somewhere. I think its time to factor the
reuseable parts out into a independent library (like glib does for
gtk), in fact I had this plan long ago.


.What parts are eligible for a standalone library

Anything which is something tool alike and useful for other projects and not
tied to Lumiera only. This are the algorithms/datastructures, allocators, tool
macros. Additionally some of the src/common things should be moved into the
library. I give some lists below.

.How to name it

Long time ago my plan was to name it 'ctlib' or 'cehlib' but meanwhile there is
enough code done by others. So I'd propose a more neutral name, still
'lumieralib' or 'lulib' would be approbiate. The only thing we have to account
for is that some parts which are too specific for Lumiera and should not be
integrated into this spinoff need either to stay in a lumiera-internal lib
(src/lib/) as currently or being moved to the respective subsystems using them
(src/backend, src/proc, src/common, ...), so the names should not clash.

.C, C++ ...

For myself I need the C parts, while there is C++ code which interfaces to the
C implementations and also a lot code which does nice C++ things on its own.
This possibly means that we should in fact make 2 packages out of this, one C
and one C++ library (where the C++ part is more than just the wrappers, but
also the tools and tricks which are currently in src/lib/ and reuseable).

.Who maintains it

Despite a spin of I think we don't want to change anything from our current
practice and maintain it by the Lumiera developers. For many parts I feel
responsible for it, but its really a part of the Lumiera codebase, despite
independently useable.

.How to maintain it

We need to decide about build system and documentation system. As build system
we may right start using scons. For documentation the situation is a but
different since some of my code uses pipadoc/asciidoc and other uses doxygen.

.What not to do

Some of the code is currently quite specific to Lumiera while it could be made
more generic. This is *NOT* subject of this RFC we may or may not do such a
refactoring but this RFC and any work resulting from this should only restrict
to simple things like necessary namespace and variable renaming and integration
in the build system.


C Parts
-------

Library
~~~~~~~
What belongs to the library

Containers
^^^^^^^^^^
 * cuckoo hashing (cuckoo.c|h)
 * linked lists (llist.h slist.h)
 * cache lists (mrucache.c|h)
 * splay trees (psplay.c|h)
 * priority queues (not done yet)

Runtime tools
^^^^^^^^^^^^^
 * error handling (error.h error.c) used by the other facilities too
 * clib convinience wrapers (safeclib.c|h) needs better name, maybe refactor
   into new facilities

Multithreading
^^^^^^^^^^^^^^
 * locking, condition variables etc. (condition.c|h (rec)mutex.c|h, rwlock ...)

Memory management
^^^^^^^^^^^^^^^^^
 * Memory pools (mpool.c|h)
 * Temporary buffers (tmpbuf.c|h)

Metaprogramming
^^^^^^^^^^^^^^^
  * preprecessor tools (ppmpl.h) move common preprocessor macros here
  * polymorphic call helper for C (vcall.h)

Interface system and module loader
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

except for some hardcoded references to 'lumiera_org' and '.lum' plugin names
this is quite generic, possibly moving this over could be postponed, but might
eventually be done.

From 'src/common'
------
interface.c interfacedescriptor.h interface.h interfaceproxy.cpp
interfaceregistry.c interfaceregistry.h plugin.c plugin_dynlib.c plugin.h
------


The 'config' system could become a candidate too if it ever gets finished and
proved useful, but for the time being its better kept in Lumiera.


Not Library
~~~~~~~~~~~
Too specific to Lumiera:
-----
luid.c luid.h time.h
-----


C++ Parts
---------

For most of the C++ parts I am not sure, ichthyo should decided upon these
(please edit this here)

Library
~~~~~~~
These look 'generic' or wrap the C parts:
------
singleton-factory.hpp singleton.hpp singleton-policies.hpp
singleton-preconfigure.hpp singleton-ref.hpp singleton-subclass.hpp
sync-classlock.hpp sync.cpp sync.hpp thread-local.hpp
typed-allocation-manager.hpp typed-counter.hpp util.cpp util-foreach.hpp
util.hpp variant.hpp
------

Not Sure
~~~~~~~~
------
access-casted.hpp advice advice.hpp allocation-cluster.cpp
allocation-cluster.hpp bool-checkable.hpp cmdline.cpp cmdline.hpp del-stash.hpp
diagnostic-context.hpp element-tracker.hpp error.hpp (currently too
lumiera specific) exception.cpp (as before) factory.hpp format.hpp
frameid.hpp functor-util.hpp handle.hpp hash-indexed.hpp iter-adapter.hpp
iter-adapter-stl.hpp iter-source.hpp itertools.hpp iter-type-binding.hpp
lifecycle.cpp lifecycleregistry.hpp lumitime-fmt.hpp lumitime.hpp
multifact-arg.hpp multifact.hpp meta/* null-value.hpp observable-list.hpp
opaque-holder.hpp optional-ref.hpp p.hpp query.cpp query.hpp ref-array.hpp
ref-array-impl.hpp result.hpp scoped-holder.hpp scoped-holder-transfer.hpp
scoped-ptrvect.hpp searchpath.cpp searchpath.hpp sub-id.hpp symbol.hpp
symbol-impl.cpp visitor-dispatcher.hpp visitor.hpp visitor-policies.hpp
wrapper.hpp wrapperptr.hpp appstate.cpp appstate.hpp basic-setup.cpp
basic-setup.hpp DIR_INFO external guifacade.cpp instancehandle.hpp option.cpp
option.hpp query subsys.cpp subsys.hpp subsystem-runner.hpp
----


Not Library
~~~~~~~~~~~
------
logging.cpp nobug-init.cpp nobug-init.hpp streamtype.cpp streamtype.hpp test/*
time/* time.cpp tree.hpp
-----

Tasks
~~~~~
// List what needs to be done to implement this Proposal:
// * first step ([green]#✔ done#)

 * decide on name, namespaces [,yellow]#WIP#
 * create git repository, setup boilerplace (build system, legalese)
   [,yellow]#WIP#
 * move all code over into the git repos, refactor (namespace renames) ()
   [,yellow]#WIP#
 * make Lumiera use the new lib [,yellow]#WIP#

Discussion
~~~~~~~~~~

Pros
^^^^
// add a fact list/enumeration which make this suitable:

 * I am already reuse much of its code, making it independent makes maintaining
   it less burden


Cons
^^^^
// fact list of the known/considered bad implications:

 * new packages, new dependencies for Lumiera instead 'batteries included'

Alternatives
^^^^^^^^^^^^
//alternatives: explain alternatives and tell why they are not viable:


Rationale
---------
//rationale: Give a concise summary why it should be done *this* way:



//Conclusion
//----------
//conclusion: When approbate (this proposal becomes a Final)
//            write some conclusions about its process:




Comments
--------
//comments: append below


//endof_comments:

''''
Back to link:/documentation/devel/rfc.html[Lumiera Design Process overview]
