Document existence of subscriptions and events API

Author: dhouck

src/main/java/li/cil/oc2/api/README.md

@@ -77,12 +77,24 @@ This can be useful for various things. For example:
     - Close and delete the file in `unmount()`.
     - Close the file in `suspend()`.
 
-### No Active Back-channel
-
-Unlike some other computer mods (e.g. OpenComputers and ComputerCraft), there is no *active* back-channel in the
-`RPCDevice` API. In other words, it is not possible for `RPCDevices` to raise events in the virtual machines. The only
-way to provide data to the virtual machines is as values returned from exposed methods. Programs running in the virtual
-machines will always have to poll for changed data.
+### Subscriptions and Events
+
+The `RPCDevice` API also lets devices raise events in the virtual machine, by implementing the `RPCEventSource`
+interface, either on the same class implementing `RPCDevice` or on the one wrapped by `ObjectDevice`. The VM will then
+be able to subscribe to events from the device, which can be sent by calling `postEvent` on the `IEventSink` passed
+to `subscribe`. An example of this is the built-in `RedstoneInterfaceBlockEntity` device.
+
+#### Note: This is mostly a new feature and there are several caveats to keep in mind when using it.
+
+- If subscriptions are used on or before OC2R version 2.2.12, they can cause a server crash if too many messages are
+  sent at once. To be safe, do not send any event in the same tick as another message, or depend on a later minimum
+  version of OC2R.
+- Right now, if a lot of messages are sent and the VM does not listen for them, some may be dropped, and there is no
+  indication to the device or VM when this happens. You cannot depend on the events being reliably delivered, and must
+  use some other communication channel if reliability is a requirement.
+- The on-the-"wire" event and subscription format is probably stable, but the VM's userspace python and lua libraries do
+  not easily support them yet, and often silently discard events when expecting a different sort of message. Better
+  support is actively being worked on.
 
 ## The `BlockDeviceProvider` and `ItemDeviceProvider`