Skip to content
This repository was archived by the owner on May 5, 2021. It is now read-only.

Commit aca1a24

Browse files
Fix code formatting style in tevent explanation
Remove tevent image that does not exist.
1 parent b373da7 commit aca1a24

File tree

1 file changed

+49
-44
lines changed

1 file changed

+49
-44
lines changed

docs/developers/internals.md

Lines changed: 49 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1276,49 +1276,53 @@ The following example illustrates the material presented in this section. In thi
12761276

12771277
Pseudocode follows:
12781278

1279-
- struct tevent_req *read_bytes_send(mem_ctx, ev, fd) {
1280-
- ...
1279+
```c
1280+
struct tevent_req *read_bytes_send(mem_ctx, ev, fd) {
1281+
...
12811282
req = tevent_req_create(talloc_ctx, &state, struct read_bytes_state);
12821283
state->fd = fd;
12831284
state->buf = talloc_size(state, BUFSIZE);
12841285
state->len = 0;
12851286
fde = tevent_add_fd(ev, state, fd, TEVENT_FD_READ, read_bytes_handler, req);
12861287
return req;
1287-
- }
1288+
}
12881289

1289-
- void read_bytes_handler(struct tevent_context *ev, struct tevent_fd *fde, void *pvt) {
1290-
- ...
1291-
- req = talloc_get_type(pvt, struct tevent_req);
1292-
- state = tevent_req_data(req, struct read_bytes_state);
1293-
- read(state->fd, buf, BUFSIZE);
1294-
- return;
1295-
}
1290+
void read_bytes_handler(struct tevent_context *ev, struct tevent_fd *fde, void *pvt) {
1291+
...
1292+
req = talloc_get_type(pvt, struct tevent_req);
1293+
state = tevent_req_data(req, struct read_bytes_state);
1294+
read(state->fd, buf, BUFSIZE);
1295+
return;
1296+
}
12961297

1297-
- int read_bytes_recv(req, tmem_ctx, uint8_t **buf, ssize_t *len) {
1298-
- ...
1299-
- state = tevent_req_data(req, struct read_bytes_state);
1300-
- *buf = talloc_steal(mem_ctx, state->buf);
1301-
- *len = state->len;
1302-
- return EOK;
1303-
- }
1298+
int read_bytes_recv(req, tmem_ctx, uint8_t **buf, ssize_t *len) {
1299+
...
1300+
state = tevent_req_data(req, struct read_bytes_state);
1301+
*buf = talloc_steal(mem_ctx, state->buf);
1302+
*len = state->len;
1303+
return EOK;
1304+
}
1305+
```
13041306
13051307
##### Caller Code
13061308
13071309
Pseudocode follows:
13081310
1309-
- void caller_func(fd, caller_data) {
1310-
- ...
1311-
- tevent_req *req = read_bytes_send(mem_ctx, ev, fd)
1312-
- tevent_req_set_callback(req, caller_func_complete, caller_data);
1313-
}
1311+
```c
1312+
void caller_func(fd, caller_data) {
1313+
...
1314+
tevent_req *req = read_bytes_send(mem_ctx, ev, fd)
1315+
tevent_req_set_callback(req, caller_func_complete, caller_data);
1316+
}
13141317
1315-
- int caller_func_complete(tevent_req *req) {
1316-
- ...
1317-
- caller_data = tevent_req_callback_data(req, struct caller_data);
1318-
- ... do something with caller_data ...
1319-
- read_bytes_recv(req, state, &dp_error);
1320-
- return dp_error;
1321-
}
1318+
int caller_func_complete(tevent_req *req) {
1319+
...
1320+
caller_data = tevent_req_callback_data(req, struct caller_data);
1321+
... do something with caller_data ...
1322+
read_bytes_recv(req, state, &dp_error);
1323+
return dp_error;
1324+
}
1325+
```
13221326

13231327
Note the distinction between an event handler and a request callback. While they are both similar in function, the tevent main loop is only aware of the events and handlers in the event context that it is monitoring. A tevent request is not managed by the main loop. Rather, the request's implementation determines when the request has completed, resulting in the request's callback being called, which uses the callback data to continue where it left off. Unlike an event, a tevent request is quite flexible, as it represents a generic asynchronous function call. Also, when a main loop calls a handler, the main loop can not call a second handler until control has been returned to it by the first handler. However, the first handler's code may “send” a tevent request, which may itself “send” a second tevent request, and so on, all before returning control to the main loop.
13241328

@@ -1328,21 +1332,22 @@ Additionally, an event's handler and `handler_data` are registered using one of
13281332

13291333
If the async computation relies on a sub-computation taking place before the async function can make progress, it can create a request with its state, and then register the subcomputation by creating a subrequest (representing the subcomputation) and setting the subrequest's callback to a function which will allow the original computation to make progress. For example, you will often see the following pattern in the codebase (note that the code listing can be read from top to bottom, almost as if the calls were synchronous):
13301334

1331-
- comp_send(memctx, inputs)
1332-
- req = tevent_req_create(memctx, &state, struct comp_state);
1333-
- ...populate state's input fields (using inputs)...
1334-
- subreq = subcomp_send(...);
1335-
- tevent_req_set_callback(subreq, comp_done, req);
1336-
- return req;
1337-
- comp_done(subreq)
1338-
- req = tevent_req_callback_data(subreq, tevent_req)
1339-
- comp_state = tevent_req_data(req, comp_state)
1340-
- ...populate state's output fields by calling comp_recv(subreq, *state->outputs)...
1341-
- ...call tevent_req_done or tevent_req_error, as appropriate...
1342-
1343-
In order to examine a nested chain of subrequests, it can be useful to create a diagram to help visualize it. The following diagram displays two such Kerberos-related visualizations. It is left as an exercise for the reader to create an SDAP-related visualization\! ;)
1344-
1345-
![image](internals_tevent.jpg)
1335+
```c
1336+
comp_send(memctx, inputs)
1337+
req = tevent_req_create(memctx, &state, struct comp_state);
1338+
...populate state's input fields (using inputs)...
1339+
subreq = subcomp_send(...);
1340+
tevent_req_set_callback(subreq, comp_done, req);
1341+
return req;
1342+
1343+
comp_done(subreq)
1344+
req = tevent_req_callback_data(subreq, tevent_req)
1345+
comp_state = tevent_req_data(req, comp_state)
1346+
...populate state's output fields by calling comp_recv(subreq, *state->outputs)...
1347+
...call tevent_req_done or tevent_req_error, as appropriate...
1348+
```
1349+
1350+
In order to examine a nested chain of subrequests, it can be useful to create a diagram to help visualize it.
13461351
13471352
### Functions
13481353

0 commit comments

Comments
 (0)