REALLoadGlobalMethod doesn't do what you might think

This topic came up recently on the forums, and so I figured it might make a bit of sense to discuss what REALLoadGlobalMethod is. It's a plugin SDK function that is part of the dynamic access set of APIs. However, it's also total misnomer, as it's job is not to load up global methods like you might think.

The duty of this API is to load up global framework methods. That's it, and nothing more. It does not, cannot and will not load up anything outside of the select handful of framework functions that we provide. This is a problem because the name of the API certainly doesn't imply that... and the parameter signature of the function exacerbates the issue by providing a parameter to specify what module to load the function from!

To understand how this API became so misplaced, you have to understand a bit of history as well as how stuff works. When we designed the dynamic access APIs, we had some architectural underpinnings that made it feasible to allow the user to load up any method from any module. It wasn't technically *possible* yet, but it was at least kinda, sorta close. So the API was designed to be general enough to serve that purpose. However, as new technologies emerged, it became quickly apparent that the original goal was an impossibility.

So why can this feature never work as the API suggests it might? There are several reasons for it... the most telling is this: dynamic access APIs are resolved at runtime. So in order for any dynamic API to work, the information is uses must be available at runtime. This is why your plugin must call REALGetClassRef to pass a REALClassRef in to REALnewInstance -- otherwise the compiler doesn't know you require use of the class reference, and it may choose to dead strip the entire class out at link time! If the class doesn't exist at runtime, then the call to REALnewInstance will fail. This is sensible when you think about (otherwise the presence of a plugin would require the entire framework to be pulled along on the *chance* that the plugin might use it!). Well... modules have no presence at runtime. Those are a design time concept -- they're just a way to group code items together. After your application is compiled, the entire concept of a module is gone. Since there's no runtime information around, the dynamic access API has no way to look up a global function from a particular module. In fact, it has no way to even look up a global function at all, because those don't exist. There's no "table" of global functions at runtime that the compiler generates -- the functions exist somewhere, and all the resolution of what functions to call has already been done (at compile time).

(Consquently, this is also why you cannot get module information from introspection at runtime.)

REALLoadGlobalMethod does *something* though -- it does manage to load up the REALbasic framework functions, and that has to work somehow. The way that works is we have an internal list of these functions within the C++ framework itself. So when you call that method, it just does a table lookup on this hard-coded list. However, that list has no correlation to the user's project. It's just a hard-coded list of stuff that is kept around solely to allow the plugin SDK to use REALLoadGlobalMethod!

This isn't to say that it's impossible to rig something up to allow the SDK access to various global methods that aren't in the framework. It would take some work, but it would certainly be possible to accomplish. But it's still an extremely complex problem to solve -- for instance, what if you wanted to load a global function up within your plugin, but the user's code never refers to the method, and so the compiler strips it out? How would you, at plugin load time, register that you require a certain *method* to exist? What's more -- what if that method wasn't something in userland, but was instead from another plugin? Basically put: why spend that much effort trying to "fix" a plugin SDK function for a construct we actively discourage people from using in the first place!

The good news is that the functionality that REALLoadGlobalMethod provides is useful in its own right (and not likely to ever go away). It's very, very rare that a plugin would require more than what is already provided for you. However, a more apt description for this plugin SDK functionality would be:

void *REALLoadFrameworkMethod( const char *prototype );

So remember -- if you use want to use REALLoadGlobalMethod, make sure you're only using it to try to load up framework functions, as it won't do anything else.