Created Usage Modes (markdown)

Usage-Modes.md

@@ -0,0 +1,60 @@
+There are two ways in which you may want to use the library. Some people will simply want to process updates as they come, while other people don't care about processing updates at all. A mix between the two if still possible.
+
+## Processing updates
+
+By default, the library won't process updates at all (while it will still send periodic pings to ensure that the connection stays alive). To enable updates, you must set `enable_updates=True` when creating a `TelegramClient`:
+
+```python
+client = TelegramClient('myself', api_id, api_hash, enable_updates=True)
+```
+
+This way, updates will be processed as soon as they arrive. This behavior is disabled by default to avoid unnecessary processing, although it's cost is hardly noticeable.
+
+If you already have a `client` created you can also enable the `.updates` member:
+
+```python
+client.updates.enabled = True
+```
+
+To add an update handler (this is, a callback method that will be called with the update object as soon as it arrives), you should make use of the following methods:
+
+```python
+def my_handler(update_object):
+    print('I received an update:', update_object)
+
+client.add_update_handler(my_handler)
+
+# You can also remove the handler at a later point:
+client.remove_update_handler(my_handler)
+
+# Or see which handlers are currently added:
+# handlers = client.list_update_handlers()
+```
+
+**You cannot invoke requests from within these handlers**. The handlers are called from a **read-only thread**, and attempting to invoke a request (hence sending it) will raise an `AssertionError`.
+
+## Reacting to updates
+
+In order to invoke some request upon receiving an update, you need your own thread. If all you need is to react to updates, you may just use the main thread instead creating a new one.
+
+To enable active update polling, do as follows:
+
+```python
+client = TelegramClient('myself', api_id, api_hash,
+                        enable_updates=True, active_updates_polling=True)
+
+# Or, if you already have a client
+client.updates.set_polling(True)
+```
+
+Now, you **must** poll updates, or your memory will eventually fill. On your thread (or simply on the main thread) do:
+
+```python
+while True:
+    # A call to .poll() will block until there's an update available
+    update = client.updates.poll()
+
+    # Here you can invoke requests with the client and use the update
+    # For instance, we can send a message to ourselves
+    client.send_message(myself, 'New update {}'.format(update))
+```