Pervasive functions for Big Data Layout for Asynchronous Computations on Spreadsheets (BLACS)

## Logical Clock The logical time allows linearization of computations, used to provide safe concurrency. With linearization of events the happened-before relation is usefull to prevent race-conditions. ## IO Operations on the sheet Both read and write functions have a logical time parameter. This time is given by the clock service. As well, to enable a multi-agent interaction each agent identifies itself with a tag. So, a cell is identified by three parameters. Its coordinates, an agent tag and a logical time. In BLACS we describe a grid in a different format. Instead of using the conventional sequence between two coordinates like A1;B2 we describe it by the dimensions of the grid. Describing grids by comprehension, allows to describe easily all kinds of grids. In particular one could describe infinite grids using special parameters, i.e. 0 lenght or width. Useful when a user doesn't know how many cells are in a given grid. ## Evaluation of a formula The evaluation of a given formula can be achieved by a single process or rather in parallel by many processes in an asynchronous way. To express this, a cell defined by a formula is as well defined by a collection of promises. A promise is formed of a date, a grid description and a constant value. Therefore, a promise of evaluation can be on a part of the formula. This allows having a collection of evaluators trying to compute the formula. The date, indicates when a promise will be valid. Before this date, the value of the promise shall not be considered. Should an evaluator fail to fulfill its promise the value data should be null, to indicate that an evaluation is still needed. ## Types ### API Types In this API types are used to describe the arguments of a function. In particular read and write requests. ### BLACS Types BLACS itself has three kind of types to describe definitions, values, none, constants (integers) and formulas (count). This types are used to ensure safety as well as make programming easier.
More information: https://github.com/BLACS
Contact Info: colin.gonzalez@openmailbox.org
Version: 0.1
BasePath:/blacs/pervasives/0.1
All rights reserved
http://apache.org/licenses/LICENSE-2.0.html

Access

Methods

[ Jump to Models ]

Table of Contents

Clock

Io

Clock

Up 
get /time/{sheet}
Returns the next logical time. (timeSheet)
The time advances after a call so that two subsequent calls are never equal.

Path parameters

sheet (required)
Path Parameter — Name of the sheet

Return type

BigDecimal

Example data

Content-Type: application/json
1.3579000000000001069366817318950779736042022705078125

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

Responses

200

successful operation BigDecimal

Io

Up 
get /{sheet}/{hash}
The response of a read request (hashSheet)
Whenever someone makes a read request, a promise is delivered. The promise has date at which the response will be read to download.

Path parameters

sheet (required)
Path Parameter — Name of the sheet
hash (required)
Path Parameter — hash handed in the ReadPromise

Return type

array[LocatedCell]

Example data

Content-Type: application/json
[ {
  "cell" : {
    "definition" : {
      "data" : [ 1.3579000000000001069366817318950779736042022705078125 ],
      "promises" : [ {
        "date" : 1.495632574829308E9,
        "domain" : [ 1, 1, 10, 5 ],
        "value" : 1024.0
      } ]
    },
    "value" : {
      "data" : ""
    }
  },
  "coords" : {
    "col" : 32,
    "row" : 42
  }
} ]

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

Responses

200

successful operation

410

IO error
Up 
post /read/{sheet}
Reads from spreadsheet (readSheet)
Reads from sheet the grid described by origin, width and length at the given time by the agent identified by tag. If the agent has no cell defined use default agent.

Path parameters

sheet (required)
Path Parameter — Name of the sheet

Consumes

This API call consumes the following media types via the Content-Type request header:

Request body

body (required)
Body Parameter —

Return type

ReadPromise

Example data

Content-Type: application/json
{
  "date" : 1.495632574829308E9,
  "hash" : "f654c60b82b85499791437fb9c7e4a5478140095"
}

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

Responses

200

successful operation ReadPromise

410

IO error
Up 
get /size/{sheet}
Returns the latest size of the sheet. (sizeSheet)
The size of the sheet at the present (latest time).

Path parameters

sheet (required)
Path Parameter — Name of the sheet

Return type

Dimensions

Example data

Content-Type: application/json
{
  "length" : 1000.0,
  "width" : 500.0
}

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

Responses

200

succesful operation Dimensions
Up 
post /write/{sheet}
Writes to spreadsheet (writeSheet)
Write on sheet the grid of dimension width by length at origin at time by agent identified with tag the cell array in the same order.

Path parameters

sheet (required)
Path Parameter — Name of the sheet

Consumes

This API call consumes the following media types via the Content-Type request header:

Request body

body (required)
Body Parameter —

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

Responses

200

successful operation

410

IO error
Up

Models

[ Jump to Methods ]

Table of Contents

  1. Cell
  2. Coordinates
  3. Definition
  4. Dimensions
  5. LocatedCell
  6. Promise
  7. ReadPromise
  8. ReadRequest
  9. Time
  10. Value
  11. WriteRequest

Cell - Up

A cell definition and value in the sheet
definition
Definition
value
Value

Coordinates - Up

The coordinates of a cell in a sheet indexed by row and column number.
col
Integer Column number
row
Integer Row number

Definition - Up

Defintions in BLACS are typed an carry along data useful for evaluators.
data
array[BigDecimal] Data of the definition.
promises
array[Promise] List of promises for the evaluation the definition.

Dimensions - Up

length (optional)
BigDecimal The length of a sheet
width (optional)
BigDecimal The width of a sheet

LocatedCell - Up

A cell and its cordinates
cell
Cell
coords
Coordinates

Promise - Up

date
BigDecimal This real time date is used to tell when a promise will be valid, the time is counted since EPOCH.
domain
array[BigDecimal] This is the domain on which the formula will be evaluated by the promise.
value
BigDecimal The result of the formula, should a promise fail the value shall be null

ReadPromise - Up

date
BigDecimal This real time date is used to tell when a promise will be valid, the time is counted since EPOCH.
hash
String The hash where the response to the read request will be available.

ReadRequest - Up

Whenever an agent reads the sheet it is performing a request. If the request is successful a new resources will be added to URI at which he will be able to read unordered collection of cells. The parameter time is the logical time at which the read is being requested. The parameter origin is coordinates to start reading a grid.
tag
String The identifier of the agent that is requesting the read.
time
Time
origin
Coordinates
length
BigDecimal A grid's length
width
BigDecimal A grid's width
filter_formulas
Boolean Require to filter formulas when performing a read
default
String Should the agent have no cell defined, read from this agent's sheet

Time - Up

Logical time

Value - Up

Values in BLACS are typed.
data
Integer Data of the value.

WriteRequest - Up

Whenever an agent writes to the sheet it is performing a request. The parameter time is the logical time at which the write is being requested. The parameter origin is coordinates to start writing a grid.
tag
String The identifier of the agent that is requesting the write
time
Time
origin
Coordinates
length
Integer A grid's length
width
Integer A grid's width
cells
array[Cell] An ordered collection of cells to be written in the grid