Lifecycle of stub creation

I'm reworking how I use stubs for indexing at the moment to try to make it more general, and I have a few questions about the stub element lifecycle.

  1. I'm assuming that when indexStub is called the whole stub tree has been built, so I can navigate within that tree to use information from other stubs, is that correct?
  2. Similarly, is createStub always called with a PSI element from a fully parsed file, i.e. a whole PSI tree?
  3. Is shouldCreateStub always called with a full PSI tree available via node.getPsi()?
  4. I understand why the createStub method is required, but why is createPsi required? My understanding was that the PSI tree would always be built by parsing the whole file, and often the stubs do not contain enough information to create a complete PsiElement. When is this used?
  5. Poking around in the code I've seen a bunch of references to a LighterAST and LightStub. What are these used for?

Thanks for any help!

Edited one of the questions after thinking about this.


1. Yes, this is correct
2. The file may not be fully parsed in the sense that not all of the chameleons may be expanded, but this should be transparent to you. You can access any information from the current file, but note that you should not access any other files.
3. Yes, it's called at the same time in the lifecycle as createStub().
4. The whole point of having stubs is that you can have a PSI tree which is backed by stubs rather than complete PSI elements. Your PSI element implementation should provide as much information as possible based on stubs (for example, something like MyClass.getName() should take the name from the stub and return it, rather than finding the name identifier node and returning its text). If your implementation accesses the AST, it will be parsed and provided for you transparently, but unnecessary AST access makes stub implementation far less efficient than it could be.
5. LighterAST is an AST implementation backed directly by PsiBuilder markers, which does not instantiate ASTNode objects for every tree node. It's slightly more efficient, but it doesn't let you access the PSI while building stubs.


Great, thanks very much Dmitry, that's very helpful.


Please sign in to leave a comment.