Improve JIT C API

Hi all,

I would like to have better C API for LLVM JIT, as I have plans to use
it from Rust. I've sent already a patch [1] that adds possibility to
create custom memory managers based on SectionMemoryManager using C API.

What I would like to have now is a possibility to access ORC through C
API somehow. The problem here is that ORC uses templates heavily. So I'm
looking for any suggestions on how to better wrap its functionality for C.

Also I would thank everybody who'll review my already sent patch.

[1] http://reviews.llvm.org/D12607

Hey Jauhien,

I’d be happy to review (as a fellow Rust dev). I’ve already added a few comments.

Richard Diamond

Hi Jauhien,

A few people have requested a C API for ORC. I don’t think ORC’s ready for a stable C API, but I’m not opposed to providing C bindings that will probably be reasonably stable in practice (though with no guarantees). I’ve actually already knocked up some trivial prototype bindings for Hayden Livingston that could serve as a base (see attached).

The next question is where unstable bindings should live. Juergen, Eric, anyone else who wants to weigh in: I looked back over the C API thread, but I don’t think we settled on a home for this kind of thing. Any thoughts? I could see either introducing a new include directory (something along the lines of include/llvm/llvm-c-bindings) or a new c-bindings project on llvm.org. The former would put all LLVM developers on the hook for maintaining the bindings, the latter would leave maintenance to users of the bindings project, and any volunteers. I prefer the second option: I don’t think core developers should be on the hook for maintaining unstable bindings - that kind of special treatment should be reserved for the stable API.

Cheers,
Lang.

OrcCBindings.tgz (4.01 KB)

Lang, aren't you going to be the major (only?) player when it comes to
Orc APIs, if you're not opposed to it having them in the C bindings
proper will certainly help. That's my vote, I understand it is
different from the previous cases but the API surface area here is
relatively small.

Hi Jauhien,

A few people have requested a C API for ORC. I don’t think ORC’s ready for a stable C API, but I’m not opposed to providing C bindings that will probably be reasonably stable in practice (though with no guarantees). I’ve actually already knocked up some trivial prototype bindings for Hayden Livingston that could serve as a base (see attached).

The next question is where unstable bindings should live. Juergen, Eric, anyone else who wants to weigh in: I looked back over the C API thread, but I don’t think we settled on a home for this kind of thing. Any thoughts? I could see either introducing a new include directory (something along the lines of include/llvm/llvm-c-bindings) or a new c-bindings project on llvm.org. The former would put all LLVM developers on the hook for maintaining the bindings, the latter would leave maintenance to users of the bindings project, and any volunteers. I prefer the second option: I don’t think core developers should be on the hook for maintaining unstable bindings - that kind of special treatment should be reserved for the stable API.

We hadn’t figured out a location. I was the one that wanted to move stable to a new directory and Jim wanted to move unstable. I think either will work ultimately, just a matter of personal preference in the “when do we count restart”.

That said, as long as you put a comment at the top saying that the ORC bindings are unstable and put them in a new file I’m not opposed to just putting them in llvm-c for now. I also don’t think I’m going to win the argument of “stable moves” so if you’d like to make a new unstable directory I’m perfectly happy with that direction too.

Thoughts?

-eric

Hi Hayden, Eric,

I’m not sure what you mean by “C bindings proper”? Historically the C API has set a high bar on stability, and I’m not willing/able to guarantee that level of stability yet. So it’s a matter of determining where we should put C bindings that don’t meet the bar for inclusion in “stable”.

Eric - Assuming that people want these in the llvm tree rather than in a separate project, I think ‘include/llvm-c/unstable’ seems like a good starting point. We can move it later if/when we come up with something better.

Cheers,
Lang.

Hi Hayden, Eric,

I’m not sure what you mean by “C bindings proper”? Historically the C API has set a high bar on stability, and I’m not willing/able to guarantee that level of stability yet. So it’s a matter of determining where we should put C bindings that don’t meet the bar for inclusion in “stable”.

Eric - Assuming that people want these in the llvm tree rather than in a separate project, I think ‘include/llvm-c/unstable’ seems like a good starting point. We can move it later if/when we come up with something better.

Up to you.

-eric

+1 to putting it in llvm-c for now (but also for good).

I really think the existing LLVM-C APIs should all be considered “reasonably stable in practice”, not “absolutely 100% stable forever”. “Reasonably stable in practice” means to me: if you need to remove a function, then, ok, do that. But make a reasonable effort to avoid doing so first, for users’ sake. And don’t change the ABI of existing functions.

And thus, if ORC is at that level (probably is?), I think it should just go in there with all the rest of them.

BTW, have a patch: http://reviews.llvm.org/D12685 saying that in more words.

Hi James,

And thus, if ORC is at that level (probably is?), I think it should just go in there with all the rest of them.

ORC is definitely not at that level yet - the attached patch was for a prototype of the APIs and lacks many features. If it goes in, I expect it to change reasonably quickly over the next few weeks/months as features are added and bugs uncovered and fixed. After that I would expect it to calm down a bit, but it’ll be a while before it could approach the kind of stability described in the document you posted for review.

I’ll keep an eye on this thread tomorrow and see what other people have to say as they get back from vacation, but I suspect the next step for the ORC APIs will be to go in to llvm/include/llvm-c/unstable. They can live there while they’re under development and move to llvm-c if/when we’re ready.

Cheers,
Lang.

Hi Lang, Hayden,

I had actually meant the underlying system, not the LLVM-C wrapper itself.

But, that's actually a good point which is not addressed by the draft policy: *when* do stability rules kick in? Instantaneously? A couple weeks of "oops" buffer time? The next release? Clearly, while a complex addition to the LLVM-C wrapper API is under development, its interface really cannot possibly be stable yet -- no matter what the underlying API's stability is, or what the intended stability is.

Saying that a stability policy doesn't apply until the next llvm release is attractive (and, is what the policy for IR changes says about IR compatibility). But my understanding is that a lot of people using llvm just work off of llvm trunk (and even make release branches from arbitrary points between releases), so that may not be the best policy?

Having the "unstable" directory be where under-active-development C API wrappers go while under development, and then graduating out when they're "done" makes some sense. That is: "unstable" should not be considered a final resting place for "unstable" APIs -- it's just for complex additions to the wrappers that are currently under development.

I'm a bit wary, because it seems like it could still end up a place where people will add stuff (better safe than sorry, so put it in unstable!), and then it will just get left there and never moved out, because that would take energy, and people are busy, and forget. So then you end up with a random subset of the API sitting in "unstable", despite being essentially unchanged for the last year or five. And of course other projects will have grown to depend on it by then, too.

Perhaps if the "install" build target excluded installing the headers from "unstable", too; that'd at least be a bit of incentive to move them out when they're ready, since it'll be annoying that they're not available in installed headers.

Hi All,

Belatedly circling back to this, with apologies for not being able to keep up at the time.

I expect the ORC C APIs to take at least a couple of release cycles to get ironed out to the point where they could be considered stable. It would be wonderful if it happened more quickly, and maybe we’ll get lucky, but I’m not counting on it. :slight_smile:

That said - the best way to get things moving is to have people use them and discover where the issues are. So with that in mind: Did we read a consensus on a reasonable staging area?

Would it be reasonable to put the prototype APIs in “include/llvm-c-unstable”?

Cheers,
Lang.

Hi All,

Belatedly circling back to this, with apologies for not being able to keep up at the time.

I expect the ORC C APIs to take at least a couple of release cycles to get ironed out to the point where they could be considered stable. It would be wonderful if it happened more quickly, and maybe we’ll get lucky, but I’m not counting on it. :slight_smile:

That said - the best way to get things moving is to have people use them and discover where the issues are. So with that in mind: Did we read a consensus on a reasonable staging area?

Nope :slight_smile: I think some people are waiting until the conference to sit down and discuss. At this point it’s probably fine to wait.

Would it be reasonable to put the prototype APIs in “include/llvm-c-unstable”?

shrug For now I’m ok with just llvm-c with a comment of “these apis are guaranteed to change use at your own risk”, or some similar idea.

-eric

Hi Eric,

I think some people are waiting until the conference to sit down and discuss. At this point it’s probably fine to wait.

That makes sense.

shrug For now I’m ok with just llvm-c with a comment of “these apis are guaranteed to change use at your own risk”, or some similar idea.

Sounds good. I’ll commit something like this over the weekend. I’d like to give people a chance to play with it before the conference so they can form initial impressions.

Cheers,
Lang.

So “over the weekend” ended up being slightly optimistic, but the initial Orc C APIs are now in tree, just in time for the dev meeting.

You’ll find the header in “llvm/include/llvm-c/OrcBindings.h”, and some test code in “unittests/ExecutionEngine/Orc/OrcCAPITest.cpp”.

There are a lot of things missing in this initial checkin. The big ones that I’m aware of are:

  1. Direct access to the compile callbacks API.

  2. Support for custom memory managers.

  3. Customization of the optimization pipeline.

If you’ve got other features that you’d like to see added please file feature requests on llvm.org/bugs.

I’ll be working on these features as time allows, but I’m pretty busy with other projects at the moment. If anyone else wants to take a shot, patches are very welcome too.

  • Lang.

Note that I’m unhappy with getting the C API improved - inf act I’m all for it -, but my understanding that thing were stale on that side while the policy is decided. Could you guys chime in there before pushing a ton of new things in the API ?

My understanding is that there is a BoF at the dev meeting where C API policy will be discussed.

I noted in the header file, but forgot to explicitly mention in my email: This new API is entirely experimental, and non-stable. It’s only going out so that people have a chance to experiment with it. I expect it to change to accommodate whatever policy is decided at or after the dev meeting.

Cheers,
Lang.