docs/atomfunctions.markdown · project-m36

git.iko.soy/project-m36

project-m36/docs/atomfunctions.markdown

75 lines 6.1 kB history raw

1# Project:M36 Extendable Atom Functions

3## Introduction

5While Project:M36 includes a set of basic function which operate on relational values (atoms in Project:M36 parlance), users may find it useful to write functions which operate on these atoms in the database context. For example, if a value represents a temperature in Celsius units, an atom function could be implemented to convert the value to Fahrenheit units.

7Other DBMSes also include this feature by way of stored functions such as with PL/pgsql, T-SQL, or PL/SQL.

9Project:M36 allows users to implement strongly-typed and pure atom functions in the Haskell language at runtime. This facility makes use of GHC, the Haskell compiler, as a runtime service. Alternatively, Haskell-based atom functions can be pre-compiled and loaded at runtime.

11## Atom Function Example

13In this example, we install an atom function to convert between Fahrenheit and Celsius temperatures where the temperatures are represented as integers of type ```Int```.

15We write the function giving it the name "celsiusToFahrenheit" with type ```Int -> Int``` which indicates to the compiler that the function take one ```Int``` argument value and returns one ```Int``` value. Finally, the body of the function is implemented in quotes or triple-quotes. Note that the function makes use of the "[ProjectM36.Base](/src/lib/ProjectM36/Base.hs)" module to handle the Atom type. The function must take a list of Atoms as arguments and return an Atom. The standard GHC Prelude is available in this AtomFunctionBody context.

17```

18TutorialD (master/main): addatomfunction "celsiusToFahrenheit" Int -> Either AtomFunctionError Int """(\((IntAtom c):_) -> pure $ IntAtom ( (c * 9 `div` 5) + 32)) :: [Atom] -> Either AtomFunctionError Atom"""

19```

21Using triple-quotes allows quotes to be used inside the string without backslash escaping, which can become tedious. The sum type using ```Either``` allows the function to return an error, if necessary.

23## Advanced Atom Function Example

25Project:M36 also supports runtime-created new data types represented as algebraic data types. Internally, these are represented as ```ConstructedAtom```s, so the atom function script must use appropriate constructors.

27In the following example, splitting the temperature values into two types make sense because it prevents accidental use of operators between the two domains. For example, a ```CelsiusTemperature``` could never be accidentially added to a ```FahrenheitTemperature``` or otherwise compared without a conversion function in between. Thus, the separation of types increases our confidence in the database results when compared to the raw ```Int``` representation above.

29```

30data CelsiusTemperature = CelsiusTemperature Int

31data FahrenheitTemperature = FahrenheitTemperature Int

33addatomfunction "celsiusToFahrenheit" CelsiusTemperature -> Either AtomFunctionError FahrenheitTemperature """(\(ConstructedAtom _ _ (IntAtom celsius:_):_) -> pure $ ConstructedAtom "Fahrenheit" (ConstructedAtomType "Fahrenheit" empty) [IntAtom (celsius * (9 `div` 5) + 32)]) :: [Atom] -> Either AtomFunctionError Atom """

34```

36First, we define our new types and use these types in the function's type definition. Next, we deconstruct the incoming ```ConstructedAtom``` argument to extract its ```Int``` value. Finally, we perform the calculation and wrap the value in a new Fahrenheit-based ```ConstructedAtom```.

38Project:M36 also supports polymorphic types when used with atom functions. Here is an implementation of the veritable ```id``` function which merely returns its argument:

40```

41addatomfunction "idTest" a -> Either AtomFunctionError a "(\(x:_) -> pure x) :: [Atom] -> Either AtomFunctionError Atom"

42```

44## Pre-compiled Atom Functions

46Compiling atom functions at runtime can incur a performance cost. To mitigate this, atom functions can be compiled by GHC to object files and then loaded into the Project:M36 server. Let's look at an [example](https://github.com/agentm/project-m36/):

48```haskell

49module DynamicAtomFunctions where

50import ProjectM36.Base

52someAtomFunctions :: [AtomFunction]

53someAtomFunctions = [AtomFunction{

54 atomFuncName = "constTrue",

55 atomFuncType = [TypeVariableType "a", BoolAtomType],

56 atomFuncBody = AtomFunctionBody Nothing (\(x:_) -> pure (BoolAtom True))}]

57```

59Any function inside any module which returns a list of `AtomFunction`s can be used to load more atom functions. First, create the Haskell object file:

61`cabal exec ghc -- examples/DynamicAtomFunctions.hs -package project-m36`

63Use cabal or stack to invoke ghc so that the project-m36 installed package will be found.

65Finally, connect to your Project:M36 database using the `tutd` client and run:

67`TutorialD (master/main): loadatomfunctions "DynamicAtomFunctions" "someFunctions" "examples/DynamicAtomFunctions.o"`

69If you see an error such as "unknown symbol", the version of the "project-m36" library installed in your sandbox is different from that with which you linked the object file. Make sure that the same versions are used in linking the server and object file.

71The atom function is now loaded and ready-to-use. Note, however, that the function must be added every time the project-m36-server starts. This will probably be improved in a future release.

73## Differences when compared to other DBMSes

75Project:M36 enforces strongly-typed atom functions. Specifically, atom functions must be pure (free of any side effects) and cannot operate on any variables other than the atoms passed in. This certainly sets stricter limits on what can be accomplished in an atom function when compared to stored functions in other DBMS products. For example, an atom function in Project:M36 would never be able to retrieve stock information from an external website because such a function cannot be pure and thus would be rejected by the atom function compiler. This restriction maintains the mathematical cohesiveness of the database and allows the DBMS to make performance-enhancing inferences it would not otherwise be able to make.