[WIP] C API Proposal

Note: The names object, function, and parameter names used in this document will not be the final names. The names are simply used as a descriptor for its intended purpose; final names will need to be properly namespaced and C-ified

Objects and typedefs

Exposed Objects

enum HashType 
{ 
  VW_DEFAULT_HASH, 
  VW_STRING_HASH, 
  VW_BYTE_HASH 
}; 

enum ErrorCode { /* TBD */ };

struct vw_feature  // Don’t expose the internal VW feature struct. 
{ 
  float value; 
  size_t weight_index; 
}; 

struct primitive_feature_space  // For manual construction and manipulation of an example's features 
{ 
  unsigned char name; 
  vw_feature* fs; 
  size_t len; 
}; 

The following types would allow for custom reductions to be plugged into the VW reduction stack. This functionality currently does not exist in any form

enum ReductionType { /* TBD */ };
enum ReductionDataType { /* TBD */ };

struct reduction // Maybe pass around copies of this to avoid the question of memory ownership. Its lightweight and won't be used in the hot path, so perf impact is minimal. Will need to be careful about versioning the struct correctly if we need to extend it 
{ 
  predict_fn predict; 
  learn_fn learn; 
  ReductionDataType input_data_type; 
  ReductionDataType output_data_type; 
  ReductionType type = CUSTOM; 
  ... // needs to partially mimic the learner struct 
}; 

Function Pointers

Note: Function signatures TBD. The following type names are used as function pointers in these documents

trace_message_t 
example_factory_t

Typedefs

typedef void* vw;

typedef void* example;

typedef void* options;

The following typedefs would allow for custom reductions to be plugged into the VW reduction stack. This functionality currently does not exist in any form

typedef void* ReductionStack;  // Whats the interaction between ReductionStack and vw? 

Internal Objects

vw – The internal representation of the VW object. Possibly in a wrapper to allow easy import and export of data across the API

example – The internal representation of the example object. Probably won't need a wrapper

options – The Some well-defined options object. Possibly a flatbuf or protobuf. TBD

The following types would allow for custom reductions to be plugged into the VW reduction stack. This functionality currently does not exist in any form

ReductionStack – Should we treat the stack as an array or a linked list? Internally it’s a linked list, but an array is easier to manipulate for a user

struct ReductionStack { 
  Stack<learner> _reduction_stack; 
  size_t _size?; 
  vw* _vw; 
}; 

 

Exposed Functions

The proposed API functions are divided into separate documents based on their primary purpose. Some functions can fall into multiple categories, and these are split relatively arbitrarily based on my own judgement. Each document is each split into 3 sections.

• The current C++ API surface that most language bindings use (found in vw.h).
• The interfaces that will be deprecated in the proposal
• The the proposed functionality.

VW Setup and Teardown

Parser and Example Lifetime

Example Manipulation

Utilities