mirror of
https://github.com/LadybirdBrowser/ladybird.git
synced 2024-11-21 15:10:19 +00:00
Documentation: Remove SerenityOS mentions from patterns reference
This commit is contained in:
parent
336bfb9e88
commit
7d4500a109
Notes:
github-actions[bot]
2024-08-17 17:52:02 +00:00
Author: https://github.com/circl-lastname Commit: https://github.com/LadybirdBrowser/ladybird/commit/7d4500a109c Pull-request: https://github.com/LadybirdBrowser/ladybird/pull/1062 Reviewed-by: https://github.com/ADKaster ✅ Reviewed-by: https://github.com/AtkinsSJ Reviewed-by: https://github.com/jamierocks Reviewed-by: https://github.com/sideshowbarker
1 changed files with 8 additions and 43 deletions
|
@ -3,12 +3,12 @@
|
||||||
## Introduction
|
## Introduction
|
||||||
|
|
||||||
Over time numerous reoccurring patterns have emerged from or were adopted by
|
Over time numerous reoccurring patterns have emerged from or were adopted by
|
||||||
the serenity code base. This document aims to track and describe them, so they
|
the Ladybird code base. This document aims to track and describe them, so they
|
||||||
can be propagated further and the code base can be kept consistent.
|
can be propagated further and the code base can be kept consistent.
|
||||||
|
|
||||||
## `TRY(...)` Error Handling
|
## `TRY(...)` Error Handling
|
||||||
|
|
||||||
The `TRY(..)` macro is used for error propagation in the serenity code base.
|
The `TRY(..)` macro is used for error propagation in the Ladybird code base.
|
||||||
The goal being to reduce the amount of boiler plate error code required to
|
The goal being to reduce the amount of boiler plate error code required to
|
||||||
properly handle and propagate errors throughout the code base.
|
properly handle and propagate errors throughout the code base.
|
||||||
|
|
||||||
|
@ -73,7 +73,7 @@ ErrorOr<void> insert_one_to_onehundred(Vector<int>& vector)
|
||||||
|
|
||||||
## Fallible Constructors
|
## Fallible Constructors
|
||||||
|
|
||||||
The usual C++ constructors are incompatible with SerenityOS's method of handling errors,
|
The usual C++ constructors are incompatible with Ladybird's method of handling errors,
|
||||||
as potential errors are passed using the `ErrorOr` return type. As a replacement, classes
|
as potential errors are passed using the `ErrorOr` return type. As a replacement, classes
|
||||||
that require fallible operations during their construction define a static function that
|
that require fallible operations during their construction define a static function that
|
||||||
is fallible instead.
|
is fallible instead.
|
||||||
|
@ -112,10 +112,10 @@ private:
|
||||||
|
|
||||||
## The `serenity_main(..)` program entry point
|
## The `serenity_main(..)` program entry point
|
||||||
|
|
||||||
Serenity has moved to a pattern where executables do not expose a normal C
|
Ladybird has moved to a pattern where executables do not expose a normal C
|
||||||
main function. A `serenity_main(..)` is exposed instead. The main reasoning
|
main function. A `serenity_main(..)` is exposed instead. The main reasoning
|
||||||
is that the `Main::Arguments` struct can provide arguments in a more idiomatic
|
is that the `Main::Arguments` struct can provide arguments in a more idiomatic
|
||||||
way that fits with the serenity API surface area. The ErrorOr<int> likewise
|
way that fits with the Ladybird's internal API surface area. The ErrorOr<int> likewise
|
||||||
allows the program to propagate errors seamlessly with the `TRY(...)` macro,
|
allows the program to propagate errors seamlessly with the `TRY(...)` macro,
|
||||||
avoiding a significant amount of clunky C style error handling.
|
avoiding a significant amount of clunky C style error handling.
|
||||||
|
|
||||||
|
@ -150,8 +150,8 @@ ErrorOr<int> serenity_main(Main::Arguments arguments)
|
||||||
|
|
||||||
## Intrusive Lists
|
## Intrusive Lists
|
||||||
|
|
||||||
[Intrusive lists](https://www.data-structures-in-practice.com/intrusive-linked-lists/) are common in the Kernel and in some specific cases
|
[Intrusive lists](https://www.data-structures-in-practice.com/intrusive-linked-lists/) are used in some specific cases
|
||||||
are used in the SerenityOS userland. A data structure is said to be
|
in Ladybird. A data structure is said to be
|
||||||
"intrusive" when each element holds the metadata that tracks the
|
"intrusive" when each element holds the metadata that tracks the
|
||||||
element's membership in the data structure. In the case of a list, this
|
element's membership in the data structure. In the case of a list, this
|
||||||
means that every element in an intrusive linked list has a node embedded
|
means that every element in an intrusive linked list has a node embedded
|
||||||
|
@ -164,41 +164,6 @@ to OOM.
|
||||||
The common pattern for declaring an intrusive list is to add the storage
|
The common pattern for declaring an intrusive list is to add the storage
|
||||||
for the intrusive list node as a private member. A public type alias is
|
for the intrusive list node as a private member. A public type alias is
|
||||||
then used to expose the list type to anyone who might need to create it.
|
then used to expose the list type to anyone who might need to create it.
|
||||||
Here is an example from the `Region` class in the Kernel:
|
|
||||||
|
|
||||||
```cpp
|
|
||||||
class Region final
|
|
||||||
: public Weakable<Region> {
|
|
||||||
|
|
||||||
public:
|
|
||||||
|
|
||||||
... snip ...
|
|
||||||
|
|
||||||
private:
|
|
||||||
bool m_syscall_region : 1 { false };
|
|
||||||
|
|
||||||
IntrusiveListNode<Region> m_memory_manager_list_node;
|
|
||||||
IntrusiveListNode<Region> m_vmobject_list_node;
|
|
||||||
|
|
||||||
public:
|
|
||||||
using ListInMemoryManager = IntrusiveList<&Region::m_memory_manager_list_node>;
|
|
||||||
using ListInVMObject = IntrusiveList<&Region::m_vmobject_list_node>;
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
You can then use the list by referencing the public type alias like so:
|
|
||||||
|
|
||||||
```cpp
|
|
||||||
class MemoryManager {
|
|
||||||
|
|
||||||
... snip ...
|
|
||||||
|
|
||||||
Region::ListInMemoryManager m_kernel_regions;
|
|
||||||
Vector<UsedMemoryRange> m_used_memory_ranges;
|
|
||||||
Vector<PhysicalMemoryRange> m_physical_memory_ranges;
|
|
||||||
Vector<ContiguousReservedMemoryRange> m_reserved_memory_ranges;
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
## Static Assertions of the size of a type
|
## Static Assertions of the size of a type
|
||||||
|
|
||||||
|
@ -263,7 +228,7 @@ argument to functions.
|
||||||
See: https://en.cppreference.com/w/cpp/utility/source_location
|
See: https://en.cppreference.com/w/cpp/utility/source_location
|
||||||
|
|
||||||
`AK::SourceLocation` is the implementation of this feature in
|
`AK::SourceLocation` is the implementation of this feature in
|
||||||
SerenityOS. It's become the idiomatic way to capture the location
|
Ladybird's AK. It's become the idiomatic way to capture the location
|
||||||
when adding extra debugging instrumentation, without resorting to
|
when adding extra debugging instrumentation, without resorting to
|
||||||
littering the code with preprocessor macros.
|
littering the code with preprocessor macros.
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue