API Improvement Plan

[bearbin]

ATM the API is quite nice, but there are some areas that are hugely weak/bad.

We need a plan to direct effort to those areas.

Here are the areas I think we should focus on:

• Threading problems - plugins should not know about threading, they should assume that everything works.
  
• API Consistency - Everything behaves differently and so lots of knowledge is needed.
  
• Direct access to the protocol is quite an important feature for special effects.
  

[worktycho]

Protocol is problematic because we also want transparent protocol versioning. As for API consistancy, I'm planing a major revamp of certain bits of the API once c++11 comes on-line, particularly the API calls that are based around functors. I view threading problems as a subclass of API problems. Whilst I don't think we can hide it completely I think we can separate it in to functions that can be called from the tick thread only, versus everything else. It then becomes a matter of documenting which hooks must be thread safe versus those that can be called from the tick thread only. We can then also add a small check using thread local storage to ensure tick thread functions are only called from the tick thread.