Update SET, schedule and tag APIs in the C target

[housengw]

This PR changes the SET, schedule and tag APIs in the C target. Here are the changes:

Format:

1. old name -> new name means that the API is renamed from old name to new name. old name is still available in the current release, but will be removed in a future release.
2. old name (deprecated) means that the old name has not been renamed, and will be removed in a future release.
3. new name (new) means that the API is introduced in the linked PR.

C target:

• SET related APIs:
  • SET -> lf_set
  • SET_ARRAY (deprecated)
  • SET_NEW (deprecated)
  • SET_NEW_ARRAY (deprecated)
  • SET_PRESENT (deprecated)
  • SET_TOKEN -> lf_set_token
  • SET_MODE -> lf_set_mode
  • lf_set_destructor (new)
  • lf_set_copy_constructor (new)
• schedule related APIs:
  • schedule -> lf_schedule
  • schedule_int -> lf_schedule_int
  • schedule_token -> lf_schedule_token
  • schedule_copy -> lf_schedule_copy
  • schedule_value -> lf_schedule_value
  • check_deadline -> lf_check_deadline
• tag_t related APIs:
  • compare_tags -> lf_tag_compare
  • get_elapsed_logical_time -> lf_time_logical_elapsed
  • get_logical_time -> lf_time_logical
  • get_current_tag -> lf_tag
  • get_microstep (deprecated)
  • get_physical_time -> lf_time_physical
  • get_elapsed_physical_time -> lf_time_physical_elapsed
  • set_physical_clock_offset -> lf_set_physical_clock_offset
  • get_start_time -> lf_time_start

These are copied from #1108. Please refer to that issue for details

[cmnrd]

I don't know the background of this change, but I would like to comment on another aspect of naming in C. "set" is a very common term and likely used in many C libraries. By using such a common function name (SET or set) we are at risk of getting name conflicts with external libraries. Since there is an API change anyway, I think it is worth considering using a prefixed form lf_set to make name conflicts less likely in C.

[edwardalee]

Undefining the macros will have the side effect that set cannot be invoked in any function defined in a preamble. I think this is OK, but we need to understand that this is a restriction. If we go with a more proprietary naming convention, as @cmnrd suggests, like lf_set, then it become less imperative to undefined the macros. Let's discuss.

[lhstrh]

Undefining the macros will have the side effect that set cannot be invoked in any function defined in a preamble. I think this is OK, but we need to understand that this is a restriction. If we go with a more proprietary naming convention, as @cmnrd suggests, like lf_set, then it become less imperative to undefined the macros. Let's discuss.

Not being able to invoke set in a preamble sounds like a great feature to me, actually.

[Soroosh129]

Another way to avoid this conflict once and for all is to put set and schedule (as pointers to functions) inside a global variable, such as ctx (inspired by the Rust target) or lf, or even self.

The programmer would then access them via ctx->set, etc.

[housengw]

lf->set is less preferable in C than lf_set IMO, and the fact that SET is a macro might make it difficult to put inside a struct.

[Soroosh129]

Not being able to invoke set in a preamble sounds like a great feature to me, actually.

I agree that this is a feature.
We want to prevent asynchronous calls to set in the preamble, and I think it's just safer to disallow set outside reaction bodies altogether. However, no one can stop a programmer from passing a pointer to set to an asynchronous thread (or just an ordinary function defined in the preamble).

[Soroosh129]

[T]he fact that SET is a macro might make it difficult to put inside a struct.

You're right.