llvm dev - Aug 2015 - [LLVMdev] [RFC] Developer Policy for LLVM C API

2015-08-17 13:47 GMT-07:00 David Blaikie <dblaikie at gmail.com>:
>
>
>
>>
>> I'd propose that the only 100% strict rule should be that if the
ABI/API
>> changes, it is done in a way that *loudly* breaks old programs -- e.g.
they
>> fail to compile, link, or run (depending on how the other-lang wrappers
are
>> accessing the API functions) -- not that you get some random weird
>> misbehavior because a function's argument types or return type has
been
>> changed.
>>
>> Ideally, if you're going to remove an API, you'd deprecate it
first, if
>> you can see the problem coming. Otherwise, oh well -- it's not
reasonable
>> to hold up LLVM development to adhere to deprecation policy on the C
API.
>>
>> That is:
>> 1) Adding new functions for new LLVM functionality: great.
>> 2) Removing old functions: if it's required -- after careful
deliberation.
>> 3) Modifying the signature of existing functions: no way.
>>
>> A couple of concrete examples:
>>
>> - Let's say you run out of space in an existing enum type (ahem,
>> LLVMAttribute...).
>>
>> You should introduce new function names, taking a better type (perhaps
>> some sort of set type, instead of a fixed-width integer...), mark the
old
>> ones deprecated so that users will update to the new functions. But,
keep
>> the old ones around so that old code can keep working. There's no
real need
>> to remove the old deprecated functions -- they'll keep working as
well as
>> they ever did with the smaller-valued attributes.
>>
>
> But does it? What if the code is checking if two functions have the same
> attributes (perhaps this is an invalid notion in the absence of information
> about specific attributes) - if you compare the smaller-ranged attributes,
> you might incorrectly conclude that these two functions have the same
> attributes. Similarly for "no attributes specified" - you look at
the enum,
> see that none are set & conclude that it's a plain, uninteresting
function
> - so you create another plain, no-attributes function you think you can
> make equivalent.
>
>
The attribute situation is fairly symptomatic of the state of the C API.
You have 2 person in this thread that tried to improve that part of the API
but eventually gave up. You have more person in that thread saying they'd
need it and have to do various workaround to get things done without it.


>
>> - Let's say you remove types from pointers.
>>
>> This is a change that can be seen coming up. So, one should fairly
early
>> on add an LLVMBuildGEP2 function that takes the extra type argument.
Leave
>> the old function name around for now (deprecated), because with the
current
>> state of LLVM, it can continue to work just fine.
>>
>> When LLVM is changed to *actually* remove all pointer types in its
core,
>> then the LLVMBuildGEP function cannot reasonably continue to exist. It
>> simply cannot work, if pointers don't have types, and the type
isn't
>> provided. So, remove it.
>>
>
> Yep, this is one we /might/ be able to manage - because we'll probably
> have to keep typed pointer information around for old bitcode
> deserialization. (but it does make the API awkward - when we finally do
> remove LLVMBuildGEP, do we rename LLVMBuildGEP2? Do we leave it there?
&
> then we need LLVMBuildGEP3, etc, as things evolve?))
>
>
LLVMBuildTypedGEP or something and we can be done with it. When The old way
is not supported anymore, LLVMBuildGEP can be removed, and eventually
recycled if the need arise.

> Also this works for writing, but not for reading - if code was expecting
> to read IR and assumed that pointers had types and bitcasts were present,
> etc - it's going to have a Bad Time reading new IR... the APIs
wouldn't
> make any sense (there would be no getPointeeType on PointerType anymore -
> there would be no Type that could be returned in response to that query)
>
> That's part of Eric's point, I think, once the API is low level
enough, it
> will churn with every change in LLVM or possible require some heroics to
> avoid that churn which will slow down LLVM's API velocity (which is
> somewhere around "ludicrous speed"), which is something we rather
like. The
> only way to make the C API more stable is to make it higher level (see
> libLTO for an example) so that we can own the migration & shelter users
> from it through that abstraction. If it's low level, it's going to
churn or
> slow us down (and probably both).
>
>
Most of it won't move from one version to another. If something fundamental
changes in LLVM from one version to the other, it is not a big deal to
update the C API to reflect it. I do not think it is going to need anything
heroic to keep it in place.
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20150817/9201e139/attachment.html>

Let's not get this die. The C API is too valuable to let this die.

I propose the following plan:
 - Add tests for the current API. This will allow to make sure that
everything works and would ensure that changes are made intentionally, nto
accidentally.
 - For area that do not exist in the C API right now, and for which support
seems needed, we establish a plan to support it according to current
functionality and planned evolution.
 - It is understood that the C API require more stability than the C++ one
as it is often used accross language boundary where type checking cannot be
done. On the other hand, no promise of stability is made so LLVM can still
evolve at "ludicrous speed". If a change to LLVM cannot be mapped to
the
current API, the API is updated.

Deal ?

2015-08-17 16:50 GMT-07:00 deadal nix <deadalnix at gmail.com>:
>
>
> 2015-08-17 13:47 GMT-07:00 David Blaikie <dblaikie at gmail.com>:
>
>>
>>
>>
>>>
>>> I'd propose that the only 100% strict rule should be that if
the ABI/API
>>> changes, it is done in a way that *loudly* breaks old programs --
e.g. they
>>> fail to compile, link, or run (depending on how the other-lang
wrappers are
>>> accessing the API functions) -- not that you get some random weird
>>> misbehavior because a function's argument types or return type
has been
>>> changed.
>>>
>>> Ideally, if you're going to remove an API, you'd deprecate
it first, if
>>> you can see the problem coming. Otherwise, oh well -- it's not
reasonable
>>> to hold up LLVM development to adhere to deprecation policy on the
C API.
>>>
>>> That is:
>>> 1) Adding new functions for new LLVM functionality: great.
>>> 2) Removing old functions: if it's required -- after careful
>>> deliberation.
>>> 3) Modifying the signature of existing functions: no way.
>>>
>>> A couple of concrete examples:
>>>
>>> - Let's say you run out of space in an existing enum type
(ahem,
>>> LLVMAttribute...).
>>>
>>> You should introduce new function names, taking a better type
(perhaps
>>> some sort of set type, instead of a fixed-width integer...), mark
the old
>>> ones deprecated so that users will update to the new functions.
But, keep
>>> the old ones around so that old code can keep working. There's
no real need
>>> to remove the old deprecated functions -- they'll keep working
as well as
>>> they ever did with the smaller-valued attributes.
>>>
>>
>> But does it? What if the code is checking if two functions have the
same
>> attributes (perhaps this is an invalid notion in the absence of
information
>> about specific attributes) - if you compare the smaller-ranged
attributes,
>> you might incorrectly conclude that these two functions have the same
>> attributes. Similarly for "no attributes specified" - you
look at the enum,
>> see that none are set & conclude that it's a plain,
uninteresting function
>> - so you create another plain, no-attributes function you think you can
>> make equivalent.
>>
>>
>
> The attribute situation is fairly symptomatic of the state of the C API.
> You have 2 person in this thread that tried to improve that part of the API
> but eventually gave up. You have more person in that thread saying
they'd
> need it and have to do various workaround to get things done without it.
>
>
>
>>
>>> - Let's say you remove types from pointers.
>>>
>>> This is a change that can be seen coming up. So, one should fairly
early
>>> on add an LLVMBuildGEP2 function that takes the extra type
argument. Leave
>>> the old function name around for now (deprecated), because with the
current
>>> state of LLVM, it can continue to work just fine.
>>>
>>> When LLVM is changed to *actually* remove all pointer types in its
core,
>>> then the LLVMBuildGEP function cannot reasonably continue to exist.
It
>>> simply cannot work, if pointers don't have types, and the type
isn't
>>> provided. So, remove it.
>>>
>>
>> Yep, this is one we /might/ be able to manage - because we'll
probably
>> have to keep typed pointer information around for old bitcode
>> deserialization. (but it does make the API awkward - when we finally do
>> remove LLVMBuildGEP, do we rename LLVMBuildGEP2? Do we leave it there?
&
>> then we need LLVMBuildGEP3, etc, as things evolve?))
>>
>>
> LLVMBuildTypedGEP or something and we can be done with it. When The old
> way is not supported anymore, LLVMBuildGEP can be removed, and eventually
> recycled if the need arise.
>
>
>> Also this works for writing, but not for reading - if code was
expecting
>> to read IR and assumed that pointers had types and bitcasts were
present,
>> etc - it's going to have a Bad Time reading new IR... the APIs
wouldn't
>> make any sense (there would be no getPointeeType on PointerType anymore
-
>> there would be no Type that could be returned in response to that
query)
>>
>> That's part of Eric's point, I think, once the API is low level
enough,
>> it will churn with every change in LLVM or possible require some
heroics to
>> avoid that churn which will slow down LLVM's API velocity (which is
>> somewhere around "ludicrous speed"), which is something we
rather like. The
>> only way to make the C API more stable is to make it higher level (see
>> libLTO for an example) so that we can own the migration & shelter
users
>> from it through that abstraction. If it's low level, it's going
to churn or
>> slow us down (and probably both).
>>
>>
> Most of it won't move from one version to another. If something
> fundamental changes in LLVM from one version to the other, it is not a big
> deal to update the C API to reflect it. I do not think it is going to need
> anything heroic to keep it in place.
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20150818/9cb1f020/attachment.html>

On Aug 18, 2015, at 10:41 PM, deadal nix <deadalnix at gmail.com>
wrote:
> Let's not get this die. The C API is too valuable to let this die.
> 
> I propose the following plan:
>  - Add tests for the current API. This will allow to make sure that
everything works and would ensure that changes are made intentionally, nto
accidentally.
>  - For area that do not exist in the C API right now, and for which support
seems needed, we establish a plan to support it according to current
functionality and planned evolution.
>  - It is understood that the C API require more stability than the C++ one
as it is often used accross language boundary where type checking cannot be
done. On the other hand, no promise of stability is made so LLVM can still
evolve at "ludicrous speed". If a change to LLVM cannot be mapped to
the current API, the API is updated.
+1 from me, with the additional "no changing existing functions'
signatures, replace with new function if necessary" rule.

Perhaps you can make a patch to the DeveloperPolicy document actually writing
down your view on the Developer Policy for the C API? Then we never have to
debate it again, because it'll be written down for future reference. And,
reviewing that patch will give people one last opportunity to object and/or
bikeshed. :)

James