Usages of @RequiresOptIn


New to the community, so if I’m saying dumb things, please say so.

I’ve seen the video on 1.5.30 and noticed the @RequiresOptIn annotation. My question / concern is that such a construct can be used to put legalese requirements in code. E.g. @RequiresOptIn(“This code is GPLv3 only, see https://…”).

I don’t think that would make our code easier or shorter if that specific use were to become common practice.

Now I’m not sure, nor could I find, what all the exact reasons are for this construct and/or if this is also it’s intended use.

I think this annotation could have many applications, for example:

  • Experimental features / unstable APIs.
  • Internal APIs that have to be available from “friend” modules (although this seems like a workaround).
  • Marking the code that requires some specific environment to run successfully, e.g. it contains prebuild native libraries or it invokes command line tools.
  • Warnings before using the code. It could be a “delicate API” that is generally discouraged, but still has some applications (e.g. GlobalScope in coroutines lib). It could be a function that may easily cause out-of-memory errors if used without care.

I’m not really sure about the GPL case. It may fit into the last category, but there is nothing really wrong in using GPLed code in general. It highly depends on the context. If there is a company that uses a lot of 3rd party libraries, some of their projects are allowed to use GPLed code and some not, then I think it makes sense to create such annotation for internal use to easily propagate GPL “flag” in internal libs. But in general case, outside of such scenario… I’m not sure.

So just to be clear, I’ve just put GPLv3 there as an example of legalese. I could have inserted “BadCorp AllYourStuffBelongsToUs” there.

@RequiresOptIn is just a tool. If we have a good reason to force people to reconsider using our code and we think benefits will be bigger than inconvenience we cause, then @RequiresOptIn exists just for such scenarios.

1 Like

How would your scenario differ from a LICENSE.TXT file with the same content? How is it different from putting that same license in the function’s docs instead, or in the source file that contains the function?

I doubt there’s much need for function-specific licenses (unless you’re the author of is-odd) in the programming world, but I guess one could use RequiresOptIn to fill that niche.

1 Like

Maybe it is the term “Optin” that does it for me. It sounds just like Consent or Compliance. Where in this case Acknowledgement or Mention seems to fit better.

Anyway, if I’m the only one that seems to care about such things, who cares.

Definition of “opt-in” from Google is:

choose to participate in something

Cambridge Dictionary:

to choose to be part of an activity, arrangement, etc.:

This is exactly what we do when using @OptIn.

1 Like