title: How to design a C / C++ library to be usable in many client languages?
body: <p>I'm planning to code a library that should be usable by a large number of people in on a wide spectrum of platforms. What do I have to consider to design it right? To make this questions more specific, there are four "subquestions" at the end.</p>
  
  <h2>Choice of language</h2>
  
  <p>Considering all the known requirements and details, I concluded that a library written in C or C++ was the way to go. I think the primary usage of my library will be in programs written in <strong>C, C++ and Java SE</strong>, but I can also think of reasons to use it from <strong>Java ME, PHP, .NET, Objective C, Python, Ruby, bash scrips, etc...</strong> Maybe I cannot target all of them, but if it's possible, I'll do it.</p>
  
  <h2>Requirements</h2>
  
  <p>It would be to much to describe the full purpose of my library here, but there are some aspects that might be important to this question:</p>
  
  <ul>
  <li>The library itself will start out small, but definitely will grow to enormous complexity, so it is not an option to maintain several versions in parallel.</li>
  <li>Most of the complexity will be hidden inside the library, though</li>
  <li>The library will construct an object graph that is used heavily inside. Some clients of the library will only be interested in specific attributes of specific objects, while other clients must traverse the object graph in some way</li>
  <li>Clients may change the objects, and the library must be notified thereof</li>
  <li>The library may change the objects, and the client must be notified thereof, if it already has a handle to that object</li>
  <li>The library must be multi-threaded, because it will maintain network connections to several other hosts</li>
  <li>While some requests to the library may be handled synchronously, many of them will take too long and must be processed in the background, and notify the client on success (or failure)</li>
  </ul>
  
  <p><em>Of course, answers are welcome no matter if they address my specific requirements, or if they answer the question in a general way that matters to a wider audience!</em></p>
  
  <h2>My assumptions, so far</h2>
  
  <p>So here are some of my assumptions and conclusions, which I gathered in the past months:</p>
  
  <ul>
  <li>Internally I can use whatever I want, e.g. C++ with operator overloading, multiple inheritance, template meta programming... as long as there is a portable compiler which handles it (think of gcc / g++)</li>
  <li>But my interface has to be a clean C interface that does not involve name mangling</li>
  <li>Also, I think my interface should only consist of functions, with basic/primitive data types (and maybe pointers) passed as parameters and return values</li>
  <li>If I use pointers, I think I should only use them to pass them back to the library, not to operate directly on the referenced memory</li>
  <li>For usage in a C++ application, I might also offer an object oriented interface (Which is also prone to name mangling, so the App must either use the same compiler, or include the library in source form)</li>
  <li>Is this also true for usage in C# ?</li>
  <li>For usage in Java SE / Java EE, the Java native interface (JNI) applies. I have some basic knowledge about it, but I should definitely double check it.</li>
  <li>Not all client languages handle multithreading well, so there should be a single thread talking to the client</li>
  <li>For usage on Java ME, there is no such thing as JNI, but I might go with <a href="http://nestedvm.ibex.org/" rel="noreferrer">Nested VM</a></li>
  <li>For usage in Bash scripts, there must be an executable with a command line interface </li>
  <li>For the other client languages, I have no idea</li>
  <li>For most client languages, it would be nice to have kind of an adapter interface written in that language. I think there are tools to automatically generate this for Java and some others</li>
  <li>For object oriented languages, it might be possible to create an object oriented adapter which hides the fact that the interface to the library is function based - but I don't know if its worth the effort</li>
  </ul>
  
  <h2>Possible subquestions</h2>
  
  <ul>
  <li>is this possible with manageable effort, or is it just too much portability?</li>
  <li>are there any good books / websites about this kind of design criteria?</li>
  <li>are any of my assumptions wrong?</li>
  <li>which open source libraries are worth studying to learn from their design / interface / souce?</li>
  <li>meta: This question is rather long, do you see any way to split it into several smaller ones? <em>(If you reply to this, do it as a comment, not as an answer)</em></li>
  </ul>