# SFBNet Class Reference

Class supporting 'service gradient routing' via the Net. More...

`#include <SFBNet.h>`

Collaboration diagram for SFBNet:

[legend]

## Data Structures
struct | Entry
## Public Types
enum | Sizes { MAX_TOTAL_SVCS = 64, MAX_LOCAL_SVCS = 32, MAX_RETURN_ROUTE_LENGTH = 100 }
| Scaling limits for SFBNet. More...
## Public Member Functions
bool | shouldTakeFirstTie ()
| Access tie-breaking strategy for equal-length routing decisions.
void | setShouldTakeFirstTie (bool on)
| Control tie-breaking strategy for equal-length routing decisions.
void | begin ()
| Initializes the Net, by registering the 'N' reflex and starting the broadcast alarm.
bool | isActive ()
| `true` if the most-recent call to begin() is newer than the most-recent call to end().
void | end ()
| Stops the Net.
void | offer (u8 service)
| Specifies that service is now locally provided.
bool | withhold (u8 service)
| Specifies that service is not (or no longer) locally provided.
bool | isOfferedByNode (u8 service)
| Is service currently being offered locally by this node?
bool | isOfferedByNet (u8 service)
| Is service being currently offered anywhere on the grid (as far as we know)?
void | openServiceStream (u8 service)
| Opens a "connection" with a service provider.
void | printf (const char *fmt,...)
| Prints formatted output to the currently open service.
void | vprintf (const char *fmt, va_list &ap)
| Prints formatted output to the currently open service.
void | printf (u8 service, const char *fmt,...)
| Prints formatted output to a provider of service, if any.
void | setBroadcastPeriod (u32 millis)
| Sets the broadcast period to approximately millis.
void | setHorizon (u32 distance)
| Sets the TTL ('Time To Live') horizon for all Net packets originating at this node to distance.
u32 | getHorizon ()
| Gets the TTL ('Time To Live') horizon used for all Net packets originating at this node.
u32 | getServiceStreamFace ()
| Get the virtual face used for printing to the internal packet buffer.
bool | neighborActive (u8 face)
| Returns `true` if we have recently heard SFBNet activity from `face`.
void | dump (u8 face, const u8 *prefix=0)
| Log internal state to face for debugging.

## Detailed Description

Class supporting 'service gradient routing' via the Net.

Allows a sketch to offer 'services' to a (region of) connected boards. Service requests from the network appear as simple reflex triggerings on the service-offering board; replies generated during reflex processing can be automatically reverse-routed to the requesting board.

Since:
  0.9.18

## Member Enumeration Documentation

enum SFBNet::Sizes

Scaling limits for SFBNet.

Increasing these values increases the SFBNet RAM footprint.

See also:
  setHorizon(u32) and setBroadcastPeriod(u32) for runtime-settable scaling parameters.

Enumerator:

  MAX_TOTAL_SVCS | Maximum services a given node can route to. RAM increases at 9*this bytes.
  MAX_LOCAL_SVCS | Maximum services a given node can provide. RAM increases at this bytes.
  MAX_RETURN_ROUTE_LENGTH | Maximum hops allowed in a return route. RAM increases at this bytes.

## Member Function Documentation

u32 SFBNet::getHorizon | ( |  | ) | `[inline]`

Gets the TTL ('Time To Live') horizon used for all Net packets originating at this node.

See also:
  setHorizon(u32)

bool SFBNet::isOfferedByNet | ( | u8 | service | ) |

Is service being currently offered anywhere on the grid (as far as we know)?

Returns:
  `true` iff it is.

See also:
  isOfferedByNode(u8 service) for a mechanism to determine if service is offered specifically by the current node.

bool SFBNet::isOfferedByNode | ( | u8 | service | ) |

Is service currently being offered locally by this node?

Returns:
  `true` iff it is.

See also:
  isOfferedByNet(u8 service) for a mechanism to determine if service is offered anywhere in the Net (not just locally).

void SFBNet::offer | ( | u8 | service | ) |

Specifies that service is now locally provided.

Changes nothing if service was already locally provided.

Blinks:
  E_API_RESOURCE_EXHAUSTED if there's no more room to offer local services

See also:
  MAX_LOCAL_SVCS

  withhold(u8)

Examples:
  netled.cpp.

void SFBNet::openServiceStream | ( | u8 | service | ) |

Opens a "connection" with a service provider.

That is, it sets the currently selected service to service, such that, when a newline is printed, the current contents of the internal packet buffer are shipped out to a provider of service.

void SFBNet::printf | ( | const char * | fmt,
|  |  | ... |
| ) |  |  |

Prints formatted output to the currently open service.

See also:
  openServiceStream(u8)

Examples:
  netled.cpp.

void SFBNet::setBroadcastPeriod | ( | u32 | millis | ) |

Sets the broadcast period to approximately millis.

Actual range of values is about 0.25 seconds to about one minute, at a granularity of about a quarter second; millis values outside that range will be clipped to the nearest value. Default value is about 5 seconds. A smaller period responds faster to node connectivity changes, but increases overall network traffic.

void SFBNet::setHorizon | ( | u32 | distance | ) |

Sets the TTL ('Time To Live') horizon for all Net packets originating at this node to distance.

Default value 6. Increasing the TTL increases the effective 'radius' of the Net, but greatly increases the amount of traffic sent during broadcasts.

Blinks:
  E_API_MAX_RANGE if distance is not less than half of MAX_RETURN_ROUTE_LENGTH.

void SFBNet::setShouldTakeFirstTie | ( | bool | on | ) | `[inline]`

Control tie-breaking strategy for equal-length routing decisions.

Determines whether shortest-direction ties should be resolved in favor of the first such direction encountered (on set to `true`) or by a random choice (on set to `false`).

See also:
  shouldTakeFirstTie()

bool SFBNet::shouldTakeFirstTie | ( |  | ) | `[inline]`

Access tie-breaking strategy for equal-length routing decisions.

Returns:
  `true` if configured to route to the first-encountered among all equally shortest directions; `false` if picking randomly among all such choices.

See also:
  setShouldTakeFirstTie(bool)

void SFBNet::vprintf | ( | const char * | fmt,
|  | va_list & | ap |
| ) |  |  |

Prints formatted output to the currently open service.

See also:
  openServiceStream(u8)

bool SFBNet::withhold | ( | u8 | service | ) |

Specifies that service is not (or no longer) locally provided.

Returns:
  `true` iff service had been being offered before this call.

See also:
  offer(u8)

Examples:
  netled.cpp.

The documentation for this class was generated from the following files:

- src/include/SFBNet.h
- src/components/library/SFBNet.cpp