MB++ Naming and Lookup

Overview:

Naming and lookup layer of MB++ mutually advertises entities on it. The advertisement is not necessarily be periodic or reliable, thus we might require explicit lookup operation between hosts.

The attribute of an entity can change, so we need (a kind of) the observer-observable pattern between the attribute and the naming/lookup layer implementation. This means when a producer/consumer/server changes a part of its attribute, the naming/lookup layer must be aware of the event to affect the change for later lookups across hosts.

Implementation Details

At this point, we are looking to use Rendezvous/Bonjour, a multicast DNS service from Apple for naming and lookup. See the documentation section on the main project page for official documentation on Bonjour. In addition, we are going to try and use the embedded library and integrate it into our application. We must also submit an official naming scheme to IANA standards board. The following is a proposal for naming:

everything will belong to the _mb domain
- MediaBroker Server: _mbserver._tcp
- MediaBroker consumer: _mbconsumer._tcp
- MediaBroker producer: _mbproducer._tcp

The types of consumers/producers can be stored in the TXT record. Additional ideas are including server loads in the server TXT record so producers/consumers can connect to the least busy server, etc.

Data Structures:

struct mb_server_attr_t
- struct mb_sockaddr_t *mb : represents a socket address where MB++ server is opening a socket
- struct mb_sockaddr_t *spd : represents a socket address where D-Stampede server is opening a socket
- char *name: represents the name of a MB++ server
struct mb_producer_attr_t
- char *name
- struct mb_stream_attr_t stream : represents the attributes of the stream
struct mb_consumer_attr_t
- char *name
struct mb_stream_attr_t
- long Start
- long End

Functions:

```
int mb_advertise_server(mb_server_attr_t *attr)
```
- Description
  - Advertise the existence of a server to a MB domain. Every MB++ server must advertise itself using this function when it started running.
- Parameters
  - attr : a pointer to a buffer that includes a server attribute.
- Returns
  - An integer representing an advertisement descriptor, or an error code (UNDEFINED yet).
- Constraints
  - Advertisement descriptor is unique in each instance of Naming / Lookup Layer. In other words, the uniqueness may not be guaranteed in a MB domain-wide.
  - [MEMORY] No memory allocation across functions.
  - [THREAD] Multi-thread safe. Multiple threads can call this concurrently or parallelly.
```
int mb_advertise_producer(mb_producer_attr_t *attr)
```
- Description
  - Advertise the existence of a producer. Every MB++ server must advertise itself using this function when it started running.
- Parameters
  - attr : a pointer to a buffer that includes a producer attribute.
- Returns
  - An integer representing an advertisement descriptor, or an error code (UNDEFINED yet).
- Constraints
  - Advertisement descriptor is unique in each instance of Naming / Lookup Layer. In other words, the uniqueness may not be guaranteed in a MB domain-wide.
  - [MEMORY] No memory allocation across functions.
  - [THREAD] Multi-thread safe. Multiple threads can call this concurrently or parallelly.
```
int mb_advertise_consumer(mb_consumer_attr_t *attr)
```
- Description
  - Advertise the existence of a consumer. Every MB++ server must advertise itself using this function when it started running.
- Parameters
  - attr : a pointer to a buffer that includes a consumer attribute.
- Returns
  - An integer representing an advertisement descriptor, or an error code (UNDEFINED yet).
- Constraints
  - Advertisement descriptor is unique in each instance of Naming / Lookup Layer. In other words, the uniqueness may not be guaranteed in a MB domain-wide.
  - [MEMORY] No memory allocation across functions.
  - [THREAD] Multi-thread safe. Multiple threads can call this concurrently or parallelly.
```
int mb_stop_advertisement(int ad)
```
- Description
  - Stop advertisement for the specified advertisement descriptor, which is returned by one of advertisement functions. If no advertisement exists for the descriptor, this returns an error code (UNDEFINED yet).
- Parameters
  - ad : an advertisement descriptor.
- Returns
  - An integer representing an advertisement descriptor.
- Constraints
  - Advertisement descriptor is unique in each instance of Naming / Lookup Layer. In other words, the uniqueness may not be guaranteed in a MB domain-wide.
  - [MEMORY] No memory allocation across functions.
  - [THREAD] Multi-thread safe. Multiple threads can call this concurrently or parallelly.
```
int mb_find_server(long timeout_msec, struct mb_server_attr_t ** attrs)
```
- Description
  - Locate MB++ servers in a MB domain in the given amount of time. Returns the number of servers, or an error code (UNDEFINED yet). If no server exists in the domain when this function is invoked, the caller will be blocked for timeout_msec milliseconds or until a new server appears in the segment. If timeout_msec is 0, this call immediately returns whether or not a server exists. If timeout_msec is less than 0, this call will never timeout.
- Parameters
  - timeout_msec : specifies the amount of time that the caller can wait for.
  - attrs : a pointer to a buffer, malloc’ed in this function, where server attributes will be stored.
- Returns
  - An integer representing the number of servers running in the domain, or an error code (UNDEFINED yet) when an error occurs.
- Constraints
  - [MEMORY] This function malloc’s one or more struct mb_server_attr_t. Callers must free them.
  - [THREAD] Multi-thread safe. Multiple threads can call this concurrently or parallelly.
```
int mb_resolve_server(long timeout_msec, struct mb_server_attr_t *template, struct mb_server_attr_t **attrs)
```
- Description
  - Locate an MB++ server in a MB domain that match the template in the given amount of time. When one or more servers are found, the attrs buffer are allocated, otherwise NULL will be set to attrs. If no server exists in the domain when this function is invoked, the caller will be blocked for timeout_msec milliseconds or until a new server appears in the domain. If timeout_msec is 0, this call immediately returns whether or not a server exists. If timeout_msec is less than 0, this call will never timeout.
- Parameters
  - timeout_msec : specifies the amount of time that the caller can wait for.
  - template : a pointer to a buffer containing a template attribute.
  - attrs : a pointer to a buffer, malloc’ed in this function, where server attributes will be stored.
- Returns
  - An integer representing the number of servers in the domain that match the template, or an error code (UNDEFINED yet) when an error occurs.
- Constraints
  - [MEMORY] This function malloc’s one or more struct mb_server_attr_t. Callers must free them.
  - [THREAD] Multi-thread safe. Multiple threads can call this concurrently or parallelly.
```
int mb_find_producer(long timeout_msec, struct mb_producer_attr_t **attrs)
```
- Description
  - Locate MB++ producers in a MB domain in the given amount of time. Returns the number of producers, or an error code (UNDEFINED yet). If no producer exists in the domain when this function is invoked, the caller will be blocked for timeout_msec milliseconds or until a new producer appears in the domain. If timeout_msec is 0, this call immediately returns whether or not a producer exists. If timeout_msec is less than 0, this call will never timeout.
- Parameters
  - timeout_msec : specifies the amount of time that the caller can wait for.
  - attrs : a pointer to a buffer, malloc’ed in this function, where producer attributes will be stored.
- Returns
  - An integer representing the number of producers in the domain, or an error code (UNDEFINED yet) when an error occurs.
- Constraints
  - [MEMORY] This function malloc’s one or more struct mb_producer_attr_t . Callers must free them.
  - [THREAD] Multi-thread safe. Multiple threads can call this concurrently or parallelly.
```
int mb_resolve_producer(long timeout_msec, struct mb_producer_attr_t *template, struct mb_producer_attr_t **attrs)
```
- Description
  - Locate an MB++ producer in a MB domain that match the template in the given amount of time. When one or more producers are found, the attrs buffer are allocated, otherwise NULL will be set to attrs. If no producer exists in the domain when this function is invoked, the caller will be blocked for timeout_msec milliseconds or until a new server appears in the segment. If timeout_msec is 0, this call immediately returns whether or not a producer exists. If timeout_msec is less than 0, this call will never timeout.
- Parameters
  - timeout_msec : specifies the amount of time that the caller can wait for.
  - template : a pointer to a buffer containing a template attribute.
  - attrs : a pointer to a buffer, malloc’ed in this function, where server attributes will be stored.
- Returns
  - An integer representing the number of producers in the domain that match the template, or an error code (UNDEFINED yet) when an error occurs.
- Constraints
  - [MEMORY] This function malloc’s one or more struct mb_producer_attr_t . Callers must free them.
  - [THREAD] Multi-thread safe. Multiple threads can call this concurrently or parallelly.
```
int mb_find_consumer(long timeout_msec, struct mb_consumer_attr_t **attrs)
```
- Description
  - Locate MB++ consumers in a MB domain in the given amount of time. Returns the number of consumers, or an error code (UNDEFINED yet). If no consumer exists in the domain when this function is invoked, the caller will be blocked for timeout_msec milliseconds or until a new consumer appears in the domain. If timeout_msec is 0, this call immediately returns whether or not a consumer exists. If timeout_msec is less than 0, this call will never timeout.
- Parameters
  - timeout_msec : specifies the amount of time that the caller can wait for.
  - attrs : a pointer to a buffer, malloc’ed in this function, where consumer attributes will be stored.
- Returns
  - An integer representing the number of consumers in the domain, or an error code (UNDEFINED yet) when an error occurs.
- Constraints
  - [MEMORY] This function malloc’s one or more struct mb_consumer_attr_t . Callers must free them.
  - [THREAD] Multi-thread safe. Multiple threads can call this concurrently or parallelly.
```
int mb_resolve_consumer(long timeout_msec, struct mb_consumer_attr_t *template, struct mb_consumer_attr_t **attrs)
```
- Description
  - Locate an MB++ consumer in a MB domain that match the template in the given amount of time. When one or more consumers are found, the attrs buffer are allocated, otherwise NULL will be set to attrs. If no consumer exists in the domain when this function is invoked, the caller will be blocked for timeout_msec milliseconds or until a new server appears in the segment. If timeout_msec is 0, this call immediately returns whether or not a consumer exists. If timeout_msec is less than 0, this call will never timeout.
- Parameters
  - timeout_msec : specifies the amount of time that the caller can wait for.
  - template : a pointer to a buffer containing a template attribute.
  - attrs : a pointer to a buffer, malloc’ed in this function, where server attributes will be stored.
- Returns
  - An integer representing the number of consumers in the domain that match the template, or an error code (UNDEFINED yet) when an error occurs.
- Constraints
  - [MEMORY] This function malloc’s one or more struct mb_consumer_attr_t . Callers must free them.
  - [THREAD] Multi-thread safe. Multiple threads can call this concurrently or parallelly.

added by Nate Rivard

Link to this Page

MB++ API last edited on 30 May 2005 at 12:11 am by adsl-214-9-48.asm.bellsouth.net