diff options
Diffstat (limited to 'src/Network/KRPC.hs')
| -rw-r--r-- | src/Network/KRPC.hs | 52 |
1 files changed, 8 insertions, 44 deletions
diff --git a/src/Network/KRPC.hs b/src/Network/KRPC.hs index 286c063e..a1767161 100644 --- a/src/Network/KRPC.hs +++ b/src/Network/KRPC.hs | |||
| @@ -6,8 +6,8 @@ | |||
| 6 | -- Portability : portable | 6 | -- Portability : portable |
| 7 | -- | 7 | -- |
| 8 | -- This module provides safe remote procedure call. One important | 8 | -- This module provides safe remote procedure call. One important |
| 9 | -- point is exceptions and errors, so be able handle them properly | 9 | -- point is exceptions and errors, so to be able handle them |
| 10 | -- we need to investigate a bit about how this all works. | 10 | -- properly we need to investigate a bit about how this all works. |
| 11 | -- Internally, in order to make method invokation KRPC makes the | 11 | -- Internally, in order to make method invokation KRPC makes the |
| 12 | -- following steps: | 12 | -- following steps: |
| 13 | -- | 13 | -- |
| @@ -41,50 +41,14 @@ | |||
| 41 | -- * Caller extracts results and finally return results of the | 41 | -- * Caller extracts results and finally return results of the |
| 42 | -- procedure call as ordinary haskell values. | 42 | -- procedure call as ordinary haskell values. |
| 43 | -- | 43 | -- |
| 44 | -- If every other error occurred caller get the 'GenericError'. All | 44 | -- If every other error occurred then caller get the |
| 45 | -- errors returned by callee are throwed as ordinary haskell | 45 | -- 'GenericError'. All errors returned by callee are throwed as |
| 46 | -- exceptions at caller side. Make sure that both callee and caller | 46 | -- ordinary haskell exceptions at caller side. Also note that both |
| 47 | -- uses the same method signatures and everything should be ok: this | 47 | -- caller and callee use plain UDP, so KRPC is unreliable. |
| 48 | -- KRPC implementation provides some level of safety through | ||
| 49 | -- types. Also note that both caller and callee use plain UDP, so | ||
| 50 | -- KRPC is unreliable. | ||
| 51 | -- | 48 | -- |
| 52 | -- Consider one tiny example. From now @caller = client@ and | 49 | -- For async 'query' use @async@ package. |
| 53 | -- @callee = server or remote@. | ||
| 54 | -- | 50 | -- |
| 55 | -- Somewhere we have to define all procedure signatures. Imagine | 51 | -- For protocol details see "Network.KRPC.Message" module. |
| 56 | -- that this is a library shared between client and server: | ||
| 57 | -- | ||
| 58 | -- > factorialMethod :: Method Int Int | ||
| 59 | -- > factorialMethod = method "factorial" ["x"] ["y"] | ||
| 60 | -- | ||
| 61 | -- Otherwise you can define this code in both client and server of | ||
| 62 | -- course. But in this case you might get into troubles: you can get | ||
| 63 | -- 'MethodUnknown' or 'ProtocolError' if name or type of method | ||
| 64 | -- will mismatch after not synced changes in client or server code. | ||
| 65 | -- | ||
| 66 | -- Now let's define our client-side: | ||
| 67 | -- | ||
| 68 | -- > main = withRemote $ \remote -> do | ||
| 69 | -- > result <- call remote (0, 6000) factorialMethod 4 | ||
| 70 | -- > assert (result == 24) $ print "Success!" | ||
| 71 | -- | ||
| 72 | -- It basically open socket with 'withRemote' and make all the other | ||
| 73 | -- steps in 'call' as describe above. And finally our server-side: | ||
| 74 | -- | ||
| 75 | -- > factorialImpl :: Int -> Int | ||
| 76 | -- > factorialImpl n = product [1..n] | ||
| 77 | -- > | ||
| 78 | -- > main = runServer [factorialMethod $ return . factorialImpl] | ||
| 79 | -- | ||
| 80 | -- Here we implement method signature from that shared lib and run | ||
| 81 | -- server with runServer by passing method table in. | ||
| 82 | -- | ||
| 83 | -- For async API use /async/ package, old API have been removed. | ||
| 84 | -- | ||
| 85 | -- For more examples see @exsamples@ or @tests@ directories. | ||
| 86 | -- | ||
| 87 | -- For protocol details see 'Remote.KRPC.Protocol' module. | ||
| 88 | -- | 52 | -- |
| 89 | module Network.KRPC | 53 | module Network.KRPC |
| 90 | ( -- * Methods | 54 | ( -- * Methods |