[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

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

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

enum HashType 
{ 
  VW_DEFAULT_HASH, 
  VW_STRING_HASH, 
  VW_BYTE_HASH 
}; 

enum ErrorCode { /* 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
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 
}; 

Typedefs

typedef void vw; 

typedef void example; 

typedef void options; 

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

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

// This stuct would allow for manual manipulation of the VW reduction stack.
// This functionality currently does not exist in any form
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