[LLVMdev] LLVMContext: Suggestions for API Changes

[John Criswell]

Owen Anderson wrote:
> On Jul 15, 2009, at 7:44 AM, John Criswell wrote:
>   
>> 1) If technically possible, add the new API first, get it working,  
>> email
>> llvmdev describing the old and new APIs, provide some lead time for
>> people to change over, and then remove the old APIs.  This makes it
>> easier to plan when I fix problems due to LLVM API changes and when I
>> can work on our own bugs. :)
>>     
>
> The high-level change was already described and discussed on LLVMdev.
>   
First, did you discuss it or announce it?  There's a difference.

With its high traffic volume, I don't read all llvmdev mails anymore.  I
pick and choose based on their subject lines.  A subject entitled "API
Change: LLVMContext" will probably get my attention while
"Multi-threading support for LLVM" will not.

Second, the only emails I remember on the topic was an email that
provided a short description of LLVMContext and some followup emails on
questions/commit messages from me.  The first message announcing
LLVMContext was too vague; it required that the reader think about the
LLVM implementation and logically deduce what was going to change.  The
text you've written below is much more clear: you say methods x, y, and
z are moving from class a to b.  That information and doxygen is usually
all I need.

What I'm suggesting is that you should announce a change in a way that
makes it easy for LLVM users to understand what they need to do to
understand their code.  The announcement can't assume that the reader
knows about LLVM internals (like how uniquing is implemented), and it
can't be part of some larger discussion on how the change should be made.

What you've written below is perfect; I think it would have been better
if you had sent it earlier.  Perhaps you did, and I missed it, or
perhaps I'm being too picky.  In that case, I apologize.

I think I've said enough on the matter.  My points are meant as
constructive criticism; use them in whatever way you feel is best.

-- John T.

> The summary is that the static factory methods on Constant and Type  
> are going away, and becoming instance methods on LLVMContext.  All of  
> the instance methods are already in place (though many just forward to  
> the static implementations for the moment).  I'm currently in the  
> process of moving the implementations over, removing the static  
> versions, and updating the LLVM tree for it.
>
> For basic constant-fetching API changes, which make up the bulk of the  
> changes, the update should be trivial:  switching to the corresponding  
> instance method on LLVMContext.  In general, I've tried to make the  
> mapping of static function names to instance method names obvious, so  
> it should be straightforward.
>
> Slightly more tricky are the API changes made incidentally to moving  
> to LLVMContext,  like the GlobalValue constructor change.  These  
> occurred because it was necessary to pass a context in where it wasn't  
> available before.  I'll try to provide more notice about these, but,  
> again, they should be relatively limited in scope.
>
> --Owen