Update backward extremity docs to make it clear that it does not indicate whether we have fetched an events' prev_events

[MadLittleMods]

Update backward extremity docs to make it clear that it does not indicate whether we have fetched an events' prev_events.

This update was spawned by this discussion: #9445 (comment)

Follow-up to #10464 where the room-dag-concepts.md developer docs were first added.

Pull Request Checklist

• Pull request is based on the develop branch
• Pull request includes a changelog file. The entry should:
  • Be a short description of your change which makes sense to users. "Fixed a bug that prevented receiving messages from other servers." instead of "Moved X method from EventStore to EventWorkerStore.".
  • Use markdown where necessary, mostly for code blocks.
  • End with either a period (.) or an exclamation mark (!).
  • Start with a capital letter.
• Pull request includes a sign off
• Code style is correct
  (run the linters)

[MadLittleMods]

These statements are not true according to the code. Actual behavior in the new part of the diff 👉

Relevant code:

synapse/synapse/storage/databases/main/events.py

Lines 2170 to 2216 in f179546

	def _update_backward_extremeties(self, txn, events):
	"""Updates the event_backward_extremities tables based on the new/updated
	events being persisted.
	This is called for new events *and* for events that were outliers, but
	are now being persisted as non-outliers.
	Forward extremities are handled when we first start persisting the events.
	"""
	# From the events passed in, add all of the prev events as backwards extremities.
	# Ignore any events that are already backwards extrems or outliers.
	query = (
	"INSERT INTO event_backward_extremities (event_id, room_id)"
	" SELECT ?, ? WHERE NOT EXISTS ("
	" SELECT 1 FROM event_backward_extremities"
	" WHERE event_id = ? AND room_id = ?"
	" )"
	" AND NOT EXISTS ("
	" SELECT 1 FROM events WHERE event_id = ? AND room_id = ? "
	" AND outlier = ?"
	" )"
	)
	txn.execute_batch(
	query,
	[
	(e_id, ev.room_id, e_id, ev.room_id, e_id, ev.room_id, False)
	for ev in events
	for e_id in ev.prev_event_ids()
	if not ev.internal_metadata.is_outlier()
	],
	)
	# Delete all these events that we've already fetched and now know that their
	# prev events are the new backwards extremeties.
	query = (
	"DELETE FROM event_backward_extremities"
	" WHERE event_id = ? AND room_id = ?"
	)
	txn.execute_batch(
	query,
	[
	(ev.event_id, ev.room_id)
	for ev in events
	if not ev.internal_metadata.is_outlier()
	],
	)

[richvdh]

... or rather, the prev_events of the oldest-in-time events we know of.

[richvdh]

would it be worth adding something like "Gives the starting point when backfilling history"?

[MadLittleMods]

... or rather, the prev_events of the oldest-in-time events we know of.

They are the oldest-in-time events we know of but sometimes we only know their event_ids. Suggestion to phrase it better?

[richvdh]

Ah yes, backward extremities are the last events we don't have, rather than the first events we do. I always get confused about that.

[richvdh]

would it be worth adding something like "Gives the starting point when backfilling history"?

[MadLittleMods]

Thanks for the review @richvdh 🐯