[llvm] [IR] Make instr-create fns with Instruction *InsertBefore non-default (PR #86132)

[Stephen Tozer via llvm-commits]

SLTozer wrote:

> But I don't really have a good handle on just how commonly used the create-and-insert overloads currently are (you probably have a better idea, as you did some mass changes in that area...)

I don't have a great sense of it, since I was mostly detecting and fixing specific patterns rather than getting a sweeping overview. I think a rough outline of a suitable update process though would be:

1. Update `Instruction::Create` methods to take a single "InsertPosition" that is constructed from either `Instruction *InsertBefore`, `BasicBlock *InsertAtEnd`, `BasicBlock::iterator InsertAt`, or `std::nullopt`.
2. Immediately deprecate the `Instruction *InsertBefore` constructor, so that any downstream users are immediately notified, and the BasicBlock version can also be deprecated later on as a prelude to making insertion iterator-only.
3. Add the new iterator methods described in the previously-mentioned RFC.
4. Remove the InsertPosition class entirely (and the argument if we do decide to allow direct or IRBuilder insertion only) while making direct insertion methods iterator-only.

This means that the only breaking steps are some insert-position arguments being deprecated at step (2), before being removed at step (4), which can be spread out over a release so that all downstream users have a chance to adapt.

https://github.com/llvm/llvm-project/pull/86132