update docs

docs/make.jl

@@ -17,6 +17,7 @@ makedocs(;
         "genserver.md",
         "api.md",
         "callbacks.md",
+        "template.md",
     ],
 )
 

docs/src/genserver.md

@@ -6,8 +6,31 @@
 > 
 > The reason for this is that concurrent code cannot be written in a side-effect free manner, and as such, is more difficult to understand and analyze than purely sequential side-effect free code. In a system involving large numbers of processes, issues of message passing ordering and potential dead- or live-lock problems can make concurrent systems very difficult to understand and program. The most common abstraction used by applications ... is the client–server abstraction. [^1]
 
-With `GenServers` a developer can write a module with purely sequential code which he then can plugin into an `Actors` protocol to get highly thread-safe, distributed and fault-tolerant code.
+## Generic Server code
 
-This keeps the concurrent code within Actors and its infrastructure modules and allows an application developer to focus on functionality.
+`GenServers` provides generic and concurrent server code for
+
+- spawning a `:genserver` actor,
+- setting and maintaining its state,
+- reacting to messages and
+- responding to the caller
+
+## Implementation Code
+
+A developer then writes an *implementation module* with purely sequential code consisting of interface and
+callback functions determining 
+
+- initial server state,
+- handling of messages and
+- what to respond to them.
+
+With [`genserver`](@ref) she plugs this module into the generic server. The :genserver actor then executes the provided callback functions on startup or on messages.
+
+Two types of requests can be issued to a server process: [`call`](https://juliaactors.github.io/Actors.jl/dev/api/#Actors.call) and [`cast`](https://juliaactors.github.io/Actors.jl/dev/api/#Actors.cast):
+
+- A `Cast` is a fire-and-forget type of request — a caller sends a message and immediately moves on to do something else.
+- A `Call` is a synchronous send-and-respond request — a caller sends a message and waits until the response arrives, the timeout occurs, or the server crashes.
+
+This keeps the concurrent code within the `Actors` infrastructure and allows an application developer to focus on functionality while getting highly thread-safe, distributed and fault-tolerant code.
 
 [^1]: Joe Armstrong: [Making reliable distributed systems in the presence of software errors](https://erlang.org/download/armstrong_thesis_2003.pdf).- p. 87

docs/src/index.md

@@ -12,6 +12,7 @@ CurrentModule = GenServers
 - [Understanding GenServers](genserver.md)
 - [Genservers API](api.md)
 - [GenServer Callbacks](callbacks.md)
+- [GenServer Template](template.md)
 
 `Genservers` is part of [`JuliaActors`](https://github.com/JuliaActors)
 

docs/src/template.md

@@ -0,0 +1,36 @@
+# GenServer Template
+
+In order to write your plugin to GenServers you can use the following template:
+
+```julia
+module MyPlugin
+using GenServers
+
+export start   # export further interface functions
+
+# Client (interface)
+
+start(default...) = genserver(@__MODULE__, default...)
+start(name, default...) = genserver(@__MODULE__, default..., name=name)
+
+# 
+# write your further interface functions here
+#
+
+# Server (callbacks)
+
+function init(default...) 
+    # write some initialization code here if needed
+    return default  # the server state gets this return value
+end
+
+function oncast(default..., msg...) 
+    # dispatch on Cast messages
+end
+
+function oncall(default..., msg...)
+    # dispatch on Call messages
+end
+
+end
+```

template/myplugin.jl

@@ -0,0 +1,30 @@
+module MyPlugin
+using GenServers
+
+export start   # export further interface functions
+
+# Client (interface)
+
+start(default...) = genserver(@__MODULE__, default...)
+start(name, default...) = genserver(@__MODULE__, default..., name=name)
+
+# 
+# write your further interface functions here
+#
+
+# Server (callbacks)
+
+function init(default...) 
+    # write some initialization code here if needed
+    return default  # the server state gets this return value
+end
+
+function oncast(default..., msg...) 
+    # dispatch on Cast messages
+end
+
+function oncall(default..., msg...)
+    # dispatch on Call messages
+end
+
+end