| Title | Format interface is hard to understand |
| Status | closed |
| Priority | nice |
| Assigned user | Gareth Rees |
| Organization | Ravenbrook |
| Description | The external format interface is complicated and hard to understand. It suffers from the following problems: 1. You have a choice of three types of format structure (mps_fmt_A_s, mps_fmt_B_s and mps_fmt_auto_header_s) which have somewhat arbitrary distinctions (for example, A and B have a useless copy method which is gone in auto_header), and no clear use cases associated with them. 2. The mechanism inhibits generality. For example, if you want to have a format with both a "class" method and a non-zero header size, you can't (the former is only available in type B, and the latter only available in type auto_header). But there's no design reason for enforcing this dichotomy. 3. Everybody who uses the MPS has to understand that formats used to have a "copy" method but now they don't. 4. Even if you are creating a format for a pool class that doesn't use one of the format methods (for example, AMCZ doesn't use the scan method), you still have to pass a method. Hence no_scan, no_skip, etc in fmtno.c [1]. 5. There's an undocument variant mps_fmt_fixed_s with no clear use case (job003322). It would be nice to be able to present a clearer, easier to understand, and more general interface. |
| Analysis | Use the keyword argument mechanism. Deprecate the existing interface and offer a new interface: mps_res_t mps_fmt_create_k(mps_fmt_t *fmt_o, mps_arena_t arena, mps_args_t args) This would take the following keyword arguments: MPS_KEY_FMT_ALIGN -- alignment (default: MPS_PF_ALIGN) MPS_KEY_FMT_HEADER_SIZE -- header size (default: 0) MPS_KEY_FMT_SCAN -- scan method MPS_KEY_FMT_SKIP -- skip method MPS_KEY_FMT_FWD -- forward method MPS_KEY_FMT_ISFWD -- is-forwarded method MPS_KEY_FMT_PAD -- pad method MPS_KEY_FMT_CLASS -- class method |
| How found | inspection |
| Evidence | [1] //info.ravenbrook.com/project/mps/master/code/fmtno.c |
| Observed in | 1.111.0 |
| Created by | Gareth Rees |
| Created on | 2013-05-28 12:09:19 |
| Last modified by | Gareth Rees |
| Last modified on | 2013-05-28 16:10:11 |
| History | 2013-05-27 GDR Created. |
| Change | Effect | Date | User | Description |
|---|---|---|---|---|
| 182277 | closed | 2013-05-28 16:10:08 | Gareth Rees | New public function mps_fmt_create_k creates an object format using the keyword argument interface. Deprecate the format variant structures (mps_fmt_A_s, mps_fmt_B_s, mps_fmt_auto_header_s, mps_fmt_fixed_s) and the old interface (mps_fmt_create_A, mps_fmt_create_B, mps_fmt_create_auto_header, mps_fmt_create_fixed). |