Skip to content

Commit

Permalink
Fix another 58 URL's (dotnet#33003)
Browse files Browse the repository at this point in the history
  • Loading branch information
danmoseley committed Feb 29, 2020
1 parent 17e2cae commit 8497763
Show file tree
Hide file tree
Showing 28 changed files with 58 additions and 58 deletions.
22 changes: 11 additions & 11 deletions docs/coding-guidelines/clr-code-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ Rules can either be imposed by invariants or team policy.

Team policy rules are not necessarily less important than invariants. For example, the rule to use [safemath.h][safemath.h] rather that coding your own integer overflow check is a policy rule. But because it deals with security, we'd probably treat it as higher priority than a very obscure (non-security) related bug.

[safemath.h]: https://github.com/dotnet/coreclr/blob/master/src/inc/safemath.h
[safemath.h]: https://github.com/dotnet/runtime/blob/master/src/coreclr/src/inc/safemath.h

One type of rule you won't find here are purely syntactic "code formatting" rules such as brace placement. While there is value in uniform stylistic conventions, we don't want to "lay down the law" on these to the extent that we do for the more semantic-oriented issues covered here. The rules included in this document are here because breaking them would do one of the following:

Expand Down Expand Up @@ -238,8 +238,8 @@ The solution is the OBJECTHANDLE. OBJECTHANDLE allocates a location from special

Handles are implemented through several layers of abstraction – the "official" interface for public use is the one described here and is exposed through [objecthandle.h][objecthandle.h]. Don't confuse this with [handletable.h][handletable.h] which contains the internals. The CreateHandle() api allocates a new location. ObjectFromHandle() dereferences the handle and returns an up-to-date reference. DestroyHandle() frees the location.

[objecthandle.h]: https://github.com/dotnet/coreclr/blob/master/src/gc/objecthandle.h
[handletable.h]: https://github.com/dotnet/coreclr/blob/master/src/gc/handletable.h
[objecthandle.h]: https://github.com/dotnet/runtime/blob/master/src/coreclr/src/gc/objecthandle.h
[handletable.h]: https://github.com/dotnet/runtime/blob/master/src/coreclr/src/gc/handletable.h

The following code fragment shows how handles are used. In practice, of course, people use GCPROTECT rather than handles for situations this simple.

Expand Down Expand Up @@ -551,7 +551,7 @@ First, look for a prebaked holder that does what you want. Some common ones are

If no existing holder fits your need, make one. If it's your first holder, start by reading [src\inc\holder.h][holder.h]. Decide if you want a holder or a wrapper. If you don't do much with a resource except acquire and release it, use a holder. Otherwise, you want the wrapper since its overloaded operators make it much easier to replace the resource variable with the wrapper.

[holder.h]: https://github.com/dotnet/coreclr/blob/master/src/inc/holder.h
[holder.h]: https://github.com/dotnet/runtime/blob/master/src/coreclr/src/inc/holder.h

Instantiate the holder or wrapper template with the required parameters. You must supply the data type being managed, the RELEASE function, the default value for uninitialized constructions, the IS_NULL function and the ACQUIRE function. Unless you're implementing a critical section holder, you can probably supply a NOP for ACQUIRE . Most resources can't be meaningfully released and reacquired so it's easier to allocate the resource outside the holder and pass it in through its constructor. For convenience, [holder.h][holder.h] defines a DoNothing<Type> template that creates a NOP ACQUIRE function for any given resource type. There are also convenience templates for writing RELEASE functions. See [holder.h][holder.h] for their definitions and examples of their use.

Expand Down Expand Up @@ -716,7 +716,7 @@ SString is the abstraction to use for unmanaged strings in CLR code. It is impor

This section will provide an overview for SString. For specific details on methods and use, see the file [src\inc\sstring.h][sstring.h]. SString has been in use in our codebase for quite a few years now so examples of its use should be easy to find.

[sstring.h]: https://github.com/dotnet/coreclr/blob/master/src/inc/sstring.h
[sstring.h]: https://github.com/dotnet/runtime/blob/master/src/coreclr/src/inc/sstring.h

An SString object represents a Unicode string. It has its own buffer which it internally manages. The string buffer is typically not referenced directly by user code; instead the string is manipulated indirectly by methods defined on SString. Ultimately there are several ways to get at the raw string buffer if such functionality is needed to interface to existing APIs. But these should be used only when absolutely necessary.

Expand Down Expand Up @@ -822,7 +822,7 @@ We used to assign levels manually, but this leads to problems when it comes time

Instead we now record the explicit dependencies as a set of rules in the src\inc\CrstTypes.def file and use a tool to automatically assign compatible levels to each Crst type. See CrstTypes.def for a description of the rule syntax and other instructions for updating Crst types.

[crst.h]: https://github.com/dotnet/coreclr/blob/master/src/vm/crst.h
[crst.h]: https://github.com/dotnet/runtime/blob/master/src/coreclr/src/vm/crst.h

### <a name="2.6.3"/>2.6.3 Creating Crsts

Expand Down Expand Up @@ -1034,7 +1034,7 @@ Here are some immediate tips for working well with the managed-debugging service
- GetFoo() - fails if a Foo does not exist. Being non-mutating, this should also be GC_NOTRIGGER. Non-mutating will also make it much easier to DAC-ize. This is what the debugger will call.
- and GetOrCreateFoo() that is built around GetFoo(). The rest of the runtime can call this.
- The debugger can then just call GetFoo(), and deal with the failure accordingly.
- If you add a new stub (or way to call managed code), make sure that you can source-level step-in (F11) it under the debugger. The debugger is not psychic. A source-level step-in needs to be able to go from the source-line before a call to the source-line after the call, or managed code developers will be very confused. If you make that call transition be a giant 500 line stub, you must cooperate with the debugger for it to know how to step-through it. (This is what StubManagers are all about. See [src\vm\stubmgr.h](https://github.com/dotnet/coreclr/blob/master/src/vm/stubmgr.h)). Try doing a step-in through your new codepath under the debugger.
- If you add a new stub (or way to call managed code), make sure that you can source-level step-in (F11) it under the debugger. The debugger is not psychic. A source-level step-in needs to be able to go from the source-line before a call to the source-line after the call, or managed code developers will be very confused. If you make that call transition be a giant 500 line stub, you must cooperate with the debugger for it to know how to step-through it. (This is what StubManagers are all about. See [src\vm\stubmgr.h](https://github.com/dotnet/runtime/blob/master/src/coreclr/src/vm/stubmgr.h)). Try doing a step-in through your new codepath under the debugger.
- **Beware of timeouts** : The debugger may completely suspend your process at arbitrary points. In most cases, the debugger will do the right thing (and suspend your timeout too), but not always. For example, if you have some other process waiting for info from the debuggee, it [may hit a timeout](https://docs.microsoft.com/en-us/archive/blogs/jmstall/why-you-sometimes-get-a-bogus-contextswitchdeadlock-mda-under-the-debugger).
- **Use CLR synchronization primitives (like Crst)**. In addition to all the reasons listed in the synchronization section, the CLR-aware primitives can cooperate with the debugging services. For example:
- The debugger needs to know when threads are modifying sensitive data (which correlates to when the threads lock that data).
Expand All @@ -1057,7 +1057,7 @@ Here are some immediate tips for working well with the managed-debugging service

Because the CLR is ultimately compiled on several different platforms, we have to be careful about the primitive types which are used in our code. Some compilers can have slightly different declarations in standard header files, and different processor word sizes can require values to have different representations on different platforms.

Because of this, we have gathered definition all of the "blessed" CLR types in a single header file, [clrtypes.h](https://github.com/dotnet/coreclr/blob/master/src/inc/clrtypes.h). In general, you should only use primitive types which are defined in this file. As an exception, you may use built-in primitive types like int and short when precision isn't particularly interesting.
Because of this, we have gathered definition all of the "blessed" CLR types in a single header file, [clrtypes.h](https://github.com/dotnet/runtime/blob/master/src/coreclr/src/inc/clrtypes.h). In general, you should only use primitive types which are defined in this file. As an exception, you may use built-in primitive types like int and short when precision isn't particularly interesting.

The types are grouped into several categories.

Expand Down Expand Up @@ -1133,7 +1133,7 @@ This item asserts that the thread is in a particular mode or declares that the f

#### <a name="2.10.1.5"/>2.10.1.5 LOADS_TYPE(_loadlevel_)

This item asserts that the function may invoke the loader and cause a type to loaded up to (and including) the indicated loadlevel. Valid load levels are taken from ClassLoadLevel enumerationin [classLoadLevel.h](https://github.com/dotnet/coreclr/blob/master/src/vm/classloadlevel.h).
This item asserts that the function may invoke the loader and cause a type to loaded up to (and including) the indicated loadlevel. Valid load levels are taken from ClassLoadLevel enumerationin [classLoadLevel.h](https://github.com/dotnet/runtime/blob/master/src/coreclr/src/vm/classloadlevel.h).

The CLR asserts if any attempt is made to load a type past the current limit set by LOADS_TYPE. A call to any function that has a LOADS_TYPE contract is treated as an attempt to load a type up to that limit.

Expand All @@ -1143,7 +1143,7 @@ These declare whether a function or callee takes any kind of EE or user lock: Cr

In TLS we keep track of the current intent (whether to lock), and actual reality (what locks are actually taken). Enforcement occurs as follows:

[contract.h]: https://github.com/dotnet/coreclr/blob/master/src/inc/contract.h
[contract.h]: https://github.com/dotnet/runtime/blob/master/src/coreclr/src/inc/contract.h

- SCAN
- A CANNOT_TAKE_LOCK function calling a CAN_TAKE_LOCK function is illegal (just like THROWS/NOTHROWS)
Expand Down Expand Up @@ -1258,4 +1258,4 @@ At a high level, DAC is a technique to enable execution of CLR algorithms from o

Various tools (most notably the debugger and SOS) rely on portions of the CLR code being properly "DACized". Writing code in this way can be tricky and error-prone. Use the following references for more details:

- The best documentation is in the code itself. See the large comments at the top of [src\inc\daccess.h](https://github.com/dotnet/coreclr/blob/master/src/inc/daccess.h).
- The best documentation is in the code itself. See the large comments at the top of [src\inc\daccess.h](https://github.com/dotnet/runtime/blob/master/src/coreclr/src/inc/daccess.h).
2 changes: 1 addition & 1 deletion docs/coding-guidelines/package-projects.md
Original file line number Diff line number Diff line change
Expand Up @@ -234,7 +234,7 @@ NETStandard/DotNet are *open* ended portable identifiers. They allow a package

Libraries should select a version of DotNet/NETStandard that supports the most frameworks. This means the library should choose the lowest version that provides all the API needed to implement their functionality. Eventually this will be the same moniker used for package resolution in the library project, AKA in `frameworks` section for the libraries project.json.

In dotnet/runtime we don't always use the package resolution for dependencies, sometimes we must use project references. Additionally we aren't building all projects with the NETStandard/DotNet identifier. This issue is tracked with https://github.com/dotnet/corefx/issues/2427. As a result we calculate the version as an added safeguard based on seeds. These seeds are listed in [Generations.json](https://github.com/dotnet/buildtools/blob/master/src/Microsoft.DotNet.Build.Tasks.Packaging/src/PackageFiles/Generations.json) and rarely change. They are a record of what libraries shipped in-box and are unchangeable for a particular framework supporting a generation. Occasionally an API change can be made even to these in-box libraries and shipped out-of-band, for example by adding a new type and putting that type in a hybrid facade. This is the only case when it is permitted to update Generations.json.
In dotnet/runtime we don't always use the package resolution for dependencies, sometimes we must use project references. Additionally we aren't building all projects with the NETStandard/DotNet identifier. This issue is tracked with https://github.com/dotnet/runtime/issues/14876. As a result we calculate the version as an added safeguard based on seeds. These seeds are listed in [Generations.json](https://github.com/dotnet/buildtools/blob/master/src/Microsoft.DotNet.Build.Tasks.Packaging/src/PackageFiles/Generations.json) and rarely change. They are a record of what libraries shipped in-box and are unchangeable for a particular framework supporting a generation. Occasionally an API change can be made even to these in-box libraries and shipped out-of-band, for example by adding a new type and putting that type in a hybrid facade. This is the only case when it is permitted to update Generations.json.

In addition to the minimum API version required by implementation, reference assemblies should only claim the NETStandard/DotNet version of the minimum implementation assembly. Just because a reference assembly only depends on API in NETStandard1.0, if its implementations only apply to frameworks supporting NETStandard1.4, it should use NETStandard1.4.

Expand Down
6 changes: 3 additions & 3 deletions docs/design/coreclr/botr/dac-notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ Marshaling Specifics

DAC marshaling works through a collection of typedefs, macros and templated types that generally have one meaning in DAC builds and a different meaning in non-DAC builds. You can find these declarations in [src\inc\daccess.h][daccess.h]. You will also find a long comment at the beginning of this file that explains the details necessary to write code that uses the DAC.

[daccess.h]: https://github.com/dotnet/runtime/src/coreclr/blob/master/src/inc/daccess.h
[daccess.h]: https://github.com/dotnet/runtime/blob/master/src/coreclr/src/inc/daccess.h

An example may be helpful in understanding how marshaling works. The common debugging scenario is represented in the following block diagram:

Expand Down Expand Up @@ -140,7 +140,7 @@ PTR types defined with DPTR are the most common in the runtime, but we also have

The GPTR and VPTR macros are common enough to warrant special mention here. Both the way we use these and their external behavior is quite similar to DPTRs. Again, marshaling is automatic and transparent. The VPTR macro declares a marshaled pointer type for a class with virtual functions. This special macro is necessary because the virtual function table is essentially an implicit extra field. The DAC has to marshal this separately, since the function addresses are all target addresses that the DAC must convert to host addresses. Treating these classes in this way means that the DAC automatically instantiates the correct implementation class, making casts between base and derived types unnecessary. When you declare a VPTR type, you must also list it in vptr\_list.h. \_\_GlobalPtr types provide base functionality to marshal both global variables and static data members through the GPTR, GVAL, SPTR and SVAL macros. The implementation of global variables is almost identical to that of static fields (both use the \_\_GlobalPtr class) and require the addition of an entry in [dacvars.h][dacvars.h]. The comments in daccess.h and dacvars.h provide more details about declaring these types.

[dacvars.h]: https://github.com/dotnet/runtime/src/coreclr/blob/master/src/inc/dacvars.h
[dacvars.h]: https://github.com/dotnet/runtime/blob/master/src/coreclr/src/inc/dacvars.h

Global and static values and pointers are interesting because they form the entry points to the target address space (all other uses of the DAC require you to have a target address already). Many of the globals in the runtime are already DACized. It occasionally becomes necessary to make a previously unDACized (or a newly introduced) global available to the DAC. By using the appropriate macros and [dacvars.h][dacvars.h] entry, you enable a post-build step (DacTableGen.exe run by the build in ndp\clr\src\dacupdatedll) to save the address of the global (from clr.pdb) into a table that is embedded into mscordacwks.dll. The DAC uses this table at run-time to determine where to look in the target address space when the code accesses a global.

Expand Down Expand Up @@ -205,7 +205,7 @@ When do you need to DACize?

Whenever you add a new feature, you will need to consider its debuggability needs and DACize the code to support your feature. You must also ensure that any other changes, such as bug fixes or code clean-up, conform to the DAC rules when necessary. Otherwise, the changes will break the debugger or SOS. If you are simply modifying existing code (as opposed to implementing a new feature), you will generally be able to determine that you need to worry about the DAC when a function you modify includes a SUPPORTS\_DAC contract. This contract has a few variants such as SUPPORTS\_DAC\_WRAPPER and LEAF\_DAC\_CONTRACT. You can find comments explaining the differences in [contract.h][contract.h]. If you see a number of DAC-specific types in the function, you should assume the code will run in DAC builds.

[contract.h]: https://github.com/dotnet/runtime/src/coreclr/blob/master/src/inc/contract.h
[contract.h]: https://github.com/dotnet/runtime/blob/master/src/coreclr/src/inc/contract.h

DACizing ensures that code in the engine will work correctly with the DAC. It is important to use the DAC correctly to marshal values from the target to the host. Target addresses used incorrectly from the host (or vice versa) may reference unmapped addresses. If addresses are mapped, the values will be completely unrelated to the values expected. As a result, DACizing mostly involves ensuring that we use PTR types for all values that the DAC needs to marshal. Another major task is to ensure that we do not allow invasive code to execute in DAC builds. In practice, this means that we must sometimes refactor code or add DACCESS\_COMPILE preprocessor directives. We also want to be sure that we add the appropriate SUPPORTS\_DAC contract. The use of this contract signals to developers that the function works with the DAC. This is important for two reasons:

Expand Down
2 changes: 1 addition & 1 deletion docs/design/coreclr/botr/garbage-collection.md
Original file line number Diff line number Diff line change
Expand Up @@ -327,7 +327,7 @@ Given WKS GC with concurrent GC on (default case), the code flow for a backgroun
Resources
=========

- [.NET CLR GC Implementation](https://raw.githubusercontent.com/dotnet/coreclr/master/src/gc/gc.cpp)
- [.NET CLR GC Implementation](https://raw.githubusercontent.com/dotnet/runtime/master/src/coreclr/src/gc/gc.cpp)
- [The Garbage Collection Handbook: The Art of Automatic Memory Management](http://www.amazon.com/Garbage-Collection-Handbook-Management-Algorithms/dp/1420082795)
- [Garbage collection (Wikipedia)](http://en.wikipedia.org/wiki/Garbage_collection_(computer_science))
- [Pro .NET Memory Management](https://prodotnetmemory.com/)
2 changes: 1 addition & 1 deletion docs/design/coreclr/botr/ryujit-tutorial.md
Original file line number Diff line number Diff line change
Expand Up @@ -677,7 +677,7 @@ Add Pattern Recognition (SampleStep2 shelveset):

### Reference
- The RyuJIT Overview document is available here:
https://github.com/dotnet/runtime/blob/master/src/corDocumentation/botr/ryujit-overview.md
https://github.com/dotnet/runtime/blob/master/docs/design/coreclr/botr/ryujit-overview.md

## Backup

Expand Down
Loading

0 comments on commit 8497763

Please sign in to comment.