Update to reflect the updates overhaul

Working-with-Updates.md

@@ -1,53 +1,48 @@
-There are two ways in which you may want to use the library. Some people will simply want to show information about updates as they come, or invoke other requests as certain events happen, while other people don't care about processing updates at all. A mix between all of these is also possible.
+The library can run in four distinguishable modes:
+* With no extra threads at all.
+* With an extra thread that receives everything as soon as possible (default).
+* With several worker threads that run your update handlers.
+* A mix of the above.
 
-If you're going to have the main thread idle (e.g. `while True: sleep(1)`), you should instead put it to good use as described on [Reacting to updates](#reacting-to-updates) instead just "listening" for updates.
+Since this section is about updates, we'll describe the simplest way to work with them.
 
-## Listening for updates
+## Using multiple workers
-
-By default, the library won't process updates at all (while it will still send periodic pings to ensure that the connection stays alive). If you want to listen for updates, simply add a new handler:
 
+When you create your client, simply pass a number to the `update_workers` parameter:
 ```python
-def my_handler(update_object):
+client = TelegramClient('session', api_id, api_hash, update_workers=4)
-    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()
 ```
 
-An update handler is nothing else than a method accepting a single parameter, the update object to be processed. Please **note** that you should only run **short-running operations** here! Any request you try to invoke from within these will `return None` so the operation ends immediately instead having to wait for it.
+4 workers should suffice for most cases (this is also the default on [Python Telegram Bot](https://python-telegram-bot.org)). You can set this value to more, or even less if you need.
-
-Updates will be processed as long as there is at least one handler added, and adding the first handler will trigger a forced synchronization of the update state (manually called through `client.sync_updates()`).
-
-**You cannot invoke requests from within these handlers**. They will all `return None`. The handlers are called from a **read-only thread**, and attempting to invoke a request (hence sending it) will have no effect.
-
-## 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.
-
-The first step is to tell the `TelegramClient` that we will be actively polling new updates:
 
+The next thing you want to do is to add a method that will be called when an [`Update`](https://lonamiwebs.github.io/Telethon/types/update.html) arrives:
 ```python
-client = TelegramClient('myself', api_id, api_hash, process_updates=True)
+def callback(update):
+    print('I received', update)
 
-# Or, if you already have a client
+client.add_update_handler(callback)
-client.updates.polling = True
+# do more work here, or simply sleep!
 ```
 
-Setting this flag to `True` will also cause the library to process updates, even if no `update_handler` was added. You should generally prefer this if you're going to only have a handler, and the main thread has no other job to do.
+That's it! Now let's do something more interesting. Every time an user talks to use, let's reply to them with the same text reversed:
-
-Now, you **must** poll updates, or your memory will eventually fill. On your thread (or simply on the main thread) do:
-
 ```python
-while True:
+from telethon.tl.types import UpdateShortMessage, PeerUser
-    # 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
+def replier(update):
-    # For instance, we can send a message to ourselves
+    if isinstance(update, UpdateShortMessage) and not update.out:
-    client.send_message(myself, 'New update {}'.format(update))
+        client.send_message(PeerUser(update.user_id), update.message[::-1])
+
+
+client.add_update_handler(callback)
+input('Press enter to stop this!')
 ```
+
+We only ask you one thing: don't keep this running for too long, or your contacts will go mad.
+
+## Spawning no worker at all
+
+**WIP**
+
+## Using the main thread instead the read thread
+
+**WIP**