Skip to content

Commit

Permalink
Update README.md (#39)
Browse files Browse the repository at this point in the history
Put cycle detection inside Risks section
  • Loading branch information
sovelten authored Nov 21, 2024
1 parent ce2598f commit e7095ff
Showing 1 changed file with 29 additions and 29 deletions.
58 changes: 29 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,35 +60,6 @@ expressing branches; Nodely allows for conditional dependencies that
defer evaluation until run time checks have determined it is necessary
to evaluate a dependency.

### Cycle Detection

Nodely provides a handy function that throws an error when a cycle has been detected in your _environment_. To use this function, simply execute the following code:

```clj
(comment
(require '[nodely.api.v0 :as nodely])
(nodely/checked-env
{:a (nodely/>value 1)
:b (nodely/>leaf (even? ?a))})
) ;; When no cycle is detected, returns env {:a #:nodely.data{:type :value, :value 1}...}
```

>Avoid using the `checked-env` function at runtime, as its calculations can be costly. It is recommended to perform this verification only during development, using the REPL.
It's important to be aware that this function may sometimes produce false positives when dealing with graphs that contain mutually exclusive conditions. Here's an example where the function might produce a false positive:

```clj
(comment
(require '[nodely.api.v0 :as nodely])
(nodely/checked-env
{:f (>if (>leaf ?c) :it-was-even! (>leaf ?e))
:e (>if (>leaf ?c) (>leaf ?f) :it-was-odd!)
:c (>leaf (even? (rand-int 2)))})
) ;; throws "Checked-env found cycles at compile time"
```

Keep in mind these limitations and double-check the results if your graph contains such scenarios.

## Definitions

### Nodes
Expand Down Expand Up @@ -358,6 +329,35 @@ core.async workers deadlock, waiting on each other to complete.
If you see evaluation hanging, start investigating for loops in your
environment.

### Cycle Detection

Nodely provides a handy function that throws an error when a cycle has been detected in your _environment_. To use this function, simply execute the following code:

```clj
(comment
(require '[nodely.api.v0 :as nodely])
(nodely/checked-env
{:a (nodely/>value 1)
:b (nodely/>leaf (even? ?a))})
) ;; When no cycle is detected, returns env {:a #:nodely.data{:type :value, :value 1}...}
```

>Avoid using the `checked-env` function at runtime, as its calculations can be costly. It is recommended to perform this verification only during development, using the REPL.

It's important to be aware that this function may sometimes produce false positives when dealing with graphs that contain mutually exclusive conditions. Here's an example where the function might produce a false positive:

```clj
(comment
(require '[nodely.api.v0 :as nodely])
(nodely/checked-env
{:f (>if (>leaf ?c) :it-was-even! (>leaf ?e))
:e (>if (>leaf ?c) (>leaf ?f) :it-was-odd!)
:c (>leaf (even? (rand-int 2)))})
) ;; throws "Checked-env found cycles at compile time"
```

Keep in mind these limitations and double-check the results if your graph contains such scenarios.

## Related Work

From our knowledge there are some libraries with similar functionality, but none of them do exactly what nodely proposes
Expand Down

0 comments on commit e7095ff

Please sign in to comment.