(#64) Update documentation

docs/Publisher-Acknowledgements.md

@@ -17,4 +17,7 @@ There is a _slight_ performance hit using using this feature. If you want to dis
 var publisher = BusClientFactory.CreateDefault(s =>
 	s.AddSingleton<IPublishAcknowledger, NoAckAcknowledger>()
 );
-```
+```
+
+## Avoiding PublishConfirmException
+There are a few potential reasons for `PublishConfirmException` being thrown. If the broker is in heavy use and/or the application publishes multiple concurrent publishes on the `PublishConfirmTimeout` should be increased. Another option is to register the `NoAckAcknowledger`.

docs/conf.py

@@ -59,9 +59,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.8.2'
+version = '1.8.12'
 # The full version, including alpha/beta/rc tags.
-release = '1.8.2'
+release = '1.8.12'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/configuration.md

@@ -72,7 +72,7 @@ Here's a sample of how the `rawrabbit.json` configuration file could look like
 * **host** is a comma seperated lists of brokers to connect to (`string`)
 * **port** is the port used when connect to a broker (`int`)
 * **vhost** is the virtual host to use on the broker (`string`)
-* **parameters** is a query string like seperated list of parameters (`string`). Currently only supports `requestTimeout` as the number of seconds before a request times out.
+* **parameters** is a query string like seperated list of parameters (`string`). Supported parameters are the properties in the `RawRabbitConfiguration` object, such as  `requestTimeout`, `persistentDeliveryMode` etc.
 
 The `ConnectionStringParser` can be used to create a configuration object
 ```csharp

docs/index.rst

@@ -3,7 +3,7 @@ Welcome to RawRabbit's documentations
 =====================================
 
 `RawRabbit` is a modern .NET client for communication over `RabbitMq <http://rabbitmq.com/>`_. It is written for `vNext <http://www.asp.net/vnext>`_ and is uses Microsoft’s new frameworks for `logging <https://github.com/aspnet/Logging)>`_, `configuration <https://github.com/aspnet/Configuration>`_ and `dependecy injection <https://github.com/aspnet/DependencyInjection)>`_ It targets traditional NET runtimes, `DNX runtimes <https://github.com/aspnet/dnx>`_ and has all the ground work done for `.NET Core <https://github.com/dotnet/core>`_ .
-
+ 
 Contents:
 
 .. toctree::
@@ -18,6 +18,7 @@ Contents:
    Message-Priority
    Multiple-Subscribers-for-Messages
    Delayed-requeue-of-messages
+   inner-workings
    rabbitmq-features
 
 

docs/inner-workings.md

@@ -0,0 +1,29 @@
+# Inner workings
+This section contains information about the inner workings of `RawRabbit`. It can be a useful reference guide for users who wants to extend or modify the standard behaviour of the framework.
+
+## ChannelFactory
+The default implementation of the `IChannelFactory` is aptly named `ChannelFactory`. It has two main methods
+
+* `GetChannelAsync` returns an existing open channel that is reused by other operations in the application.
+* `CreateChannelAsync` return an new, open channel that the caller is responsible to close.
+
+### Avoiding 'Pipelining' exceptions
+It is forbidden to perform multiple synchronous operations on the same channel. Note that synchronous and asynchronous in this section does not refer to Microsoft's `Task` execution, but rahter how the call is handled by the broker. Synchronous operations include declaring queues and exchanges. It is not adviced to use `GetChannelAsync` and perform a synchronious operation, as you may get a `Pipelining of requests forbidden` exception.
+
+### Managing channel count
+The `ChannelFactory` is configured with the `ChannelFactoryConfiguration` object. The default behaviour is to re-use the same open channel whenever `GetChannelAsync` is called. `MaxChannelCount` states the maximum amout of channels in the channel pool.
+
+#### Initialize multiple channels
+The property `InitialChannelCount` can be used to define the number of channels that will be initialied as the `ChannelFactory` is initialzed.
+
+#### Dynamic scaling of channel count
+It is possible to open and close aditional channels if the workload for the currently open channels are above the specified threshold `WorkThreshold`. Note that `EnableScaleUp` and/or `EnableScaleDown` needs to be set to `true` to have scaling enabled. `ScaleInterval` defines the interval for checking if scaling should be performed. If scaling down is enable, the `GracefulCloseInterval` is used to know how long to wait before closing the channel. It is recommended to let the graceful close interval be a couple of minutes to make sure that the channel is not in used in other classes.
+
+### Alternative implementations
+The `ThreadBasedChannelFactory` uses a `ThreadLocal<IModel>` property to make sure that channels are only used in one thread. 
+
+## ConsumerFactory
+It is the consumer factory's responsibility to wire up and return an `IRawConsumer`. The `IRawConsumer` has to implementations, `EventingRawConsumer` (default) that inherits from `EventingBasicConsumer` and `QueueingRawConsumer` that inherits from `QueueingBasicConsumer`.
+
+## TopologyProvider
+The `TopologyProvider` has async methods for creating topology features, such as queues and exchanges. In order to prevent pipelinging exception, it uses it's own private channel that is disposes two seconds after last usage. It keeps a list of queues and exchanges that is has declared, so that if a `DeclareQueueAsync` is called for a queue recently declared, it returns without doing a roundtrip to the broker.