diff --git a/doc/pragma-skiss.txt b/doc/pragma-skiss.txt index 9fb2912c0169f759f6dd8dbf40aa4929743f87d4..62b54022154d25eb3abd20e9682d827f55b21e54 100644 --- a/doc/pragma-skiss.txt +++ b/doc/pragma-skiss.txt @@ -1,7 +1,62 @@ +Discussion 141023 + +TODO: + +*** new labcomm packet types: + TYPE_DEF = 0x03 // for (possibly) hierarchical type definitions + TYPE_BINDING = 0x04 // binding a sample def to a type def + +*** rewrite malloc of received samples to utilize the packet length field + to allocate a single object before parsing the sample byte stream + +*** labcomm language: add type for type_ref to facilitate references to + labcomm sample_defs (and type_defs) in (primarily) pragmas + E.g., sample ... foo; + sample ... bar; + + sample struct { + ... + type[2] some_refs; + } some_pragma; + + my_lc_some_pragma sp; + + sp.some_refs = {&labcomm_signature_my_lc_foo, + &labcomm_signature_my_lc_bar}; + + labcomm_encode_my_lc_some_pragma(enc, &sp); + + This is to avoid exposing local_to_remote and remote_to_local + +*** refactor {encoder,decoder}registry to separate the actual encoder + from the registry + + - currently, the assignment of local indices is done in the "constructor" + which means that the registries will be very thin + +*** labcomm_pragma_builder(struct labcomm_encoder *enc); + + - looks like an encoder to enable reuse of the generated encode functions + - allocates memory in the enclosing encoder, enc. + - deallocates memory when packet is sent + +*** Pragma handler + - is a decoder, to which the user registers handlers for pragma samples + - has/gets a byte_array_reader in the context + - the "surrounding" decoder will deallocate the pragma packet when the + pragma handler returns + + + + +______________________________________________________________ +______________preliminary sketch of pragma____________________ + + A pragma "packet" is a sequence of fields, where each field is a labcomm sample (in order to keep labcomm in-band self-describing). -A pragma packet has a type, which is a globally unique string +A pragma packet has a type, which is a globally unique string (e.g., java package-like name, URI, or UUID) One predefined pragma sample type is labcomm_type_ref, which is used to refer @@ -20,8 +75,8 @@ struct labcom_pragma_packet * = labcomm_pragma_new(struct labcomm_encoder e*, void labcomm_pragma_add_ref(struct labcomm_signature sig); // the semantics if more than one type reference field is undefined -// (as far as labcomm is concerned). -// One possible (pragma-type defined) semantic is that the latest type +// (as far as labcomm is concerned). +// One possible (pragma-type defined) semantic is that the latest type // reference applies to the fields following it. A pragma packet is (under the hood) a struct labcomm_encoder, so that we @@ -37,13 +92,13 @@ labcomm_pragma_send(pp, enc); #define labcomm_pragma_add_field(some_pragma_sample_type, value) \ - labcomm_encode_#some_pragma_sample_type, value) + labcomm_encode_#some_pragma_sample_type, value) -int labcomm_encode_test_twoLines( struct labcomm_encoder *e, +int labcomm_encode_test_twoLines( struct labcomm_encoder *e, test_twoLines *v) { -return labcomm_internal_encode(e, - &labcomm_signature_test_twoLines, +return labcomm_internal_encode(e, + &labcomm_signature_test_twoLines, (labcomm_enc oder_function) encode_test_twoLines, v); } @@ -56,16 +111,30 @@ alt 1. standard handlers, parameter pragma_type to handle function -- this means adding a parameter to all handlers (where null means not pragma) +void handle_some_pragma(some_pragma *v, void *context, char * pragma_type); + alt 2. standard handlers, but separate register_pragma_handler function use the handler context to store and communicate pragma-specific data. -- this means that the decoder interface needs to be extended, and that the handler context for pragmas need to be specified - (by labcomm) + (by labcomm) -1. +alt 3 have a single handler for pragma packets as the interface upwards + from the labcomm lib. That handler is then responsible for managing + and multiplexing pragma types based on the type field in the pragma + packet. -void handle_some_pragma(some_pragma *v, void *context, char * pragma_type); + The labcomm libraries can provide a default implementation of a + pragma_handler, to facilitate the common cases and reduce the + amount of boilerplate code. + +struct pragma_packet { + char *pragma_type; + char *packed_data; +} + +void handle_pragma(struct pragma_packet *p, void *context);